에이전트
에이전트 (Agent)
모델이 작업을 추론하고, 다음에 무엇을 할지 스스로 결정하고, 필요할 때 도구를 사용해 사용자의 요청을 완수하는 챗 스타일 앱이에요. 다단계 워크플로를 설계하지 않고 모델이 사용 가능한 도구로 작업을 어떻게 접근할지 자율적으로 결정하게 하고 싶을 때 사용합니다. 예를 들어 실시간 데이터를 가져오고 차트를 만들고 결과를 요약하는 데이터 분석 어시스턴트를 만들 때죠.
출처: 공식문서
참고: 새로운 종류의 에이전트가 베타로 제공되고 있어요. 자체 샌드박스에서 동작하고, 한 번 만들면 챗 앱으로 또는 워크플로 안에서 쓸 수 있습니다. 여기 다루는 것은 그 레거시 에이전트 앱입니다.
에이전트는 대화당 최대 500개 메시지 또는 2,000 토큰의 히스토리를 유지합니다. 어느 한도든 넘으면 가장 오래된 메시지를 제거합니다. 대화 시작 문구, 후속 질문 제안 같은 선택 기능도 지원하고요 — 자세한 건 App Toolkit 문서를 참고하세요.
구성하기
프롬프트 작성
프롬프트는 모델이 무엇을 하고, 어떻게 응답하고, 어떤 제약을 따를지 알려줍니다. 에이전트에서 프롬프트는 모델이 작업을 어떻게 추론하고 언제 도구를 쓸지 정하는 데도 도움을 주므로, 기대하는 워크플로를 구체적으로 기술하세요. 효과적인 프롬프트 작성 팁입니다.
- 페르소나 정의: 모델이 누구로 행동하고 어떤 전문성을 활용할지 기술합니다.
- 출력 형식 명시: 기대하는 구조, 길이, 스타일을 기술합니다.
- 제약 설정: 무엇을 피하고 어떤 규칙을 따를지 알려줍니다.
- 도구 사용 안내: 특정 도구를 이름으로 언급하고 언제 써야 하는지 기술합니다.
- 워크플로 개요: 복잡한 작업을 모델이 따라야 할 논리적 단계로 나눕니다.
변수로 동적 프롬프트 만들기
매번 프롬프트를 다시 쓰지 않고 에이전트를 사용자·상황에 맞추려면 변수를 추가하세요. 예를 들어 데이터 분석가 에이전트가 도메인을 변수로 받는 경우가 있어요.
You are a data analyst specializing in {{domain}}. Help users explore and understand their data.
When asked a question, use available data tools to fetch the relevant information. If the result suits a visual format, generate a chart. Explain your findings in plain language.
Keep responses concise. If a question is ambiguous, ask for clarification before fetching data.
프롬프트 작성 중 / > New Variable로 이름 붙은 자리표시자를 빠르게 삽입하고 나중에 Variables 섹션에서 구성할 수 있습니다. 입력에 맞는 변수 유형을 고르세요.
- Short Text: 최대 256자. 이름·이메일·제목처럼 한 줄에 들어가는 짧은 텍스트.
- Paragraph: 길이 제한 없는 긴 텍스트. 자세한 설명을 위한 여러 줄 입력.
- Select: 미리 정의된 옵션을 보여주는 드롭다운 메뉴.
- Number: 숫자 값만 허용. 수량·평점·ID처럼 수치 처리가 필요한 데이터.
- Checkbox: 예/아니오. 체크하면
true, 아니면false. - API-based Variable: 런타임에 외부 API에서 변수 값을 가져옵니다. 실시간 날씨나 DB 레코드 같은 외부 소스의 동적 데이터가 필요할 때 사용하세요.
Label Name은 각 입력 필드의 최종 사용자 노출 이름입니다.
AI로 프롬프트 생성 또는 개선
Generate를 클릭하면 LLM이 프롬프트 초안을 써 줍니다. 원하는 걸 처음부터 기술하거나 current_prompt를 참조해 무엇을 개선할지 지정할 수 있고, Ideal Output에 예시를 넣으면 더 정확한 결과를 얻어요.
Dify 도구로 에이전트 확장
텍스트 생성 너머의 작업(실시간 데이터 가져오기, 웹 검색, DB 질의 등)을 위해 모델이 외부 서비스·API와 상호작용하게 하려면 Dify 도구를 추가하세요. 모델은 각 쿼리에 따라 언제 어떤 도구를 쓸지 스스로 결정합니다. 이를 더 정밀하게 안내하려면 프롬프트에서 도구 이름을 언급하고 언제 사용해야 하는지 기술하세요.
추가한 도구는 비활성화·제거할 수 있고 구성을 수정할 수도 있습니다. 도구가 인증을 요구하면 기존 자격 증명을 선택하거나 새로 만드세요. 기본 자격 증명을 바꾸려면 Integrations > Tools > Tool Plugin으로 갑니다.
최대 반복 (Maximum Iterations)
Agent Settings의 Maximum Iterations는 모델이 단일 요청에 대해 '생각 → 도구 호출 → 결과 처리'의 추론·행동 사이클을 반복할 수 있는 횟수를 제한합니다. 여러 도구 호출이 필요한 복잡한 다단계 작업에서는 이 값을 늘리세요. 값이 높을수록 지연 시간과 토큰 비용이 증가합니다.
응답을 자체 데이터에 근거시키기
모델 응답을 일반 지식이 아니라 우리 데이터에 근거시키려면 지식 베이스를 추가하세요. 모델이 각 사용자 쿼리를 지식 베이스 설명과 대조해 검색이 필요한지 스스로 결정합니다 — 프롬프트에 지식 베이스를 언급할 필요가 없어요.
주의할 점: 에이전트 앱에는 앱 수준 검색 설정이 없습니다. 각 지식 베이스는 우리가 구성한 자체 설정으로 독립적으로 질의됩니다. 여러 개를 추가하면 에이전트가 어떤 걸 질의할지 고르고, 결과를 서로 리랭킹하지 않아요.
특정 문서 내에서 검색
기본적으로 검색은 지식 베이스 전체를 대상으로 합니다. 특정 문서로 제한하려면 수동 또는 자동 메타데이터 필터링을 활성화하세요. 검색 정밀도를 높여주며, 지식 베이스가 크거나 다른 컨텍스트의 콘텐츠가 섞여 있을 때 특히 유용합니다. 자세한 건 Metadata 문서를 참고하세요.
멀티모달 입력 처리
최종 사용자가 파일을 업로드하게 하려면 해당 멀티모달 기능을 지원하는 모델을 선택하세요. 모델이 지원하면 Vision·Audio·Document 같은 파일 유형 토글이 나타나고 필요에 따라 활성화할 수 있습니다. 모델의 지원 모달리티는 태그로 빠르게 확인할 수 있어요.
Vision 아래 Settings를 클릭하면 파일 수용·처리 방식을 구성합니다.
- Resolution: 이미지 처리의 디테일 수준만 제어. High는 복잡한 이미지에 정확도가 높지만 토큰을 더 쓰고, Low는 단순 이미지에 적은 토큰으로 빠릅니다.
- Upload Method: 기기에서 업로드, URL 붙여넣기, 둘 다 중 선택.
디버그 & 프리뷰
오른쪽 프리뷰 패널에서 에이전트를 실시간으로 테스트하세요. 모델을 고르고 메시지를 입력해 에이전트가 어떻게 응답하는지 확인합니다. 모델의 파라미터를 조정해 응답 생성을 제어할 수 있는데, 사용 가능한 파라미터·프리셋은 모델마다 다릅니다. 다른 모델의 출력을 비교하려면 Debug as Multiple Models로 최대 4개 모델을 동시에 실행해 보세요.
추론에 강하고 도구 호출을 네이티브로 지원하는 모델을 고르는 걸 권장합니다. 에이전트는 언제 도구를 쓸지, 어떤 도구가 맞는지, 결과를 어떻게 해석할지 판단해야 하는데, 이는 모델의 추론 능력에 달려 있어요. Agent Settings에서 시스템이 에이전트 모드를 자동 표시하므로 모델의 도구 호출 지원을 확인할 수 있습니다.
- Function Calling: 네이티브 지원이 있는 모델. 도구를 직접 호출할 수 있습니다.
- ReAct: 그 외의 모델. Dify가 프롬프팅 전략으로 도구 사용을 안내합니다.
배포
결과가 마음에 들면 Publish를 클릭해 앱을 공개합니다. 배포 옵션의 전체 목록은 Publish 문서에서 확인하세요.