에이전트 빌드
에이전트 빌드 (Build an Agent)
새 에이전트를 만들고 구성하는 방법을 단계별로 설명하는 페이지예요. 능력(capability)을 손으로 설정하거나 채팅으로 묘사하며 만들고(Build by Chatting), 미리보기와 배포까지 다룹니다.
출처: 공식문서
⚠️ 새 에이전트는 현재 베타 상태입니다.
에이전트 만들기
Agents에서 Create > Create from Blank를 클릭하고 에이전트 이름을 지어주세요. 선택적으로 Research Assistant 같은 역할과 설명을 추가할 수 있어요. 나머지는 모두 Configure에서 다듬습니다. 공유된 DSL 파일에서 에이전트를 만들려면 Import DSL file을 선택하세요. 스킬과 파일은 포함되지 않으므로 가져온 뒤 추가해야 합니다.
에이전트 생성·관리는 Editor 역할 이상이 필요합니다.
능력 구성하기 (Configure Its Capabilities)
각 능력을 손으로 설정하거나, 원하는 것을 묘사하며 Build mode에서 채팅으로 만들 수 있어요. Configure에서 설정한 것들은 모두 에이전트의 능력으로 저장되어 이후 모든 작업에서 사용됩니다. 별도로 에이전트는 20 GB 저장 공간을 가진 자체 샌드박스 안에서 작업하며, 진행하며 명령을 실행하고 파일을 처리합니다.
에이전트의 능력은 여기서만 바꿀 수 있습니다. 최종 사용자가 배포된 에이전트에게 자신의 프롬프트·스킬·도구를 바꿔 달라고 해도 바꿔지지 않아요.
모델 (Model)
에이전트가 구동할 채팅 모델을 고르세요. 에이전트는 언제 행동할지, 어떤 도구가 맞는지, 결과를 어떻게 읽을지 판단해야 하므로 추론에 강하고 도구 호출을 네이티브로 지원하는 모델을 선호하세요. 에이전트 성능은 모델에 따라 오르내리므로 최신 모델을 고르는 게 좋습니다. 오래된 모델은 종종 샌드박스를 제대로 활용하지 못해요 — 작업이 필요해도 명령을 실행하거나 도구를 설치하지 않는 게 대표적인 증상입니다.
프롬프트 (Prompt)
프롬프트에 에이전트의 역할과 작업 접근 방식을 설정하세요. 어떻게 추론할지, 언제 도구에 기댈지, 무엇을 피할지 구체적으로 기술하는 게 좋습니다. 다루면 좋을 몇 가지입니다.
- 페르소나와 목표: 에이전트가 누구로 행동하고 무엇을 이루려 하는지.
- 접근 방식: 일반적인 작업에 기대하는 단계나 순서.
- 도구·파일 사용: 각각을 언제 사용할지, 이름을 명시해서.
- 출력: 돌려받고 싶은 형식, 길이, 톤.
에이전트를 특정 스킬·파일·도구로 안내할 수도 있고 선택을 에이전트에 맡길 수도 있습니다.
- 프롬프트에서
/로 직접 참조해 원하는 위치에서 바로 쓰게 합니다. 특정 단계가 특정 요소에 의존할 때 가장 좋습니다. - 그냥 해당 섹션에 추가하고 에이전트가 언제 쓸지 스스로 결정하게 합니다. 에이전트의 판단을 신뢰하고 모든 움직임을 스크립트화하지 않으려 할 때 좋아요.
스킬 (Skills)
스킬은 에이전트가 특정 작업 하나를 위해 따르는 절차입니다. 에이전트의 전반적 역할을 정하는 프롬프트와 달리, 스킬은 그 작업 하나만 다룹니다. 예를 들어 지원 에이전트의 프롬프트는 "어떤 문제든 처리하는 고객 도우미"라는 역할을 정하고, refund-requests 스킬은 환불만 다룰 수 있어요 — 주문 조회, 30일 내 환불만, 마지막에 헬프센터 링크로 끝맺기처럼요.
Add를 클릭해 스킬 패키지를 업로드하세요: 안에 SKILL.md가 들어 있는 .zip 또는 .skill 파일, 최대 50 MB입니다. 패키지 형식은 Agent Skills를 참고하세요. Build mode에서 에이전트가 스킬을 직접 만들어 주게 할 수도 있습니다.
Dify 도구나 파일을 에이전트의 자체 능력으로 만들려면 스킬 패키지 안이 아니라 에이전트에 직접 추가하세요.
파일 (Files)
파일은 에이전트가 작업하며 읽을 수 있는 참조 문서예요 — 스펙, 템플릿, 가이드라인 같은 것들요. 스킬과 달리 파일은 실행할 절차가 아니라 그냥 읽을 자료입니다. 크기 제한은 파일 유형에 따라 달라요.
| 파일 유형 | 제한 |
|---|---|
| 문서 (Documents) | 15 MB |
| 이미지 (Images) | 10 MB |
| 비디오 (Video) | 100 MB |
| 오디오 (Audio) | 50 MB |
Build mode에서 에이전트가 파일을 만들어 여기에 저장하게 할 수도 있습니다. 에이전트가 만들고 저장하는 파일은 각각 최대 50 MB로 제한됩니다.
도구 (Tools)
채팅 너머로 행동할 수 있게 에이전트에 Dify 도구를 주세요: 워크스페이스의 플러그인, 커스텀 API, 워크플로, MCP 서버 등이죠. 일부 도구는 사용 전에 인증이 필요합니다.
여기 추가한 Dify 도구 외에도, 에이전트는 필요할 때 샌드박스 안에서 자체적으로 명령줄 도구를 설치·실행할 수 있습니다. 그 도구들은 Tools 목록에는 나타나지 않아요. Build mode에서 에이전트가 설치한 도구는 배포 후에도 유지될 수 있지만, 배포된 실행 중에 설치된 것은 임시입니다.
환경 변수 (Environment Variables)
Advanced Settings 아래 환경 변수를 추가할 수 있어요: 에이전트가 작업하며 샌드박스 안에서 읽을 수 있는 키-값 쌍입니다. 예를 들어 에이전트의 스킬들이 모두 같은 주문 시스템과 연동한다고 해볼게요 — 하나는 재고를 확인하고, 하나는 주문을 접수하고, 하나는 보고서를 뽑죠. 시스템 주소를 여기에 ORDER_API_URL로 저장하면 모든 스크립트가 이름으로 읽습니다. 테스트 시스템에서 프로덕션으로 바꾸려면 이 값 하나만 갱신하면 전부 따라옵니다. .env 파일을 가져와 한 번에 여러 개를 추가할 수도 있고, Build mode에서 에이전트가 설정하게 할 수도 있어요.
채팅으로 만들기 (Build by Chatting)
모든 것을 손으로 설정하는 대신, 에이전트가 무엇을 해야 하는지 묘사하며 채팅으로 만들 수 있습니다. 대화하며 에이전트가 스스로 스킬·파일·환경 변수를 설정해요. 첫 메시지의 예시는 다음과 같습니다.
Build an agent that turns raw meeting notes into structured minutes: attendees, decisions, and action items.
우리는 살아 있는 에이전트와 대화하는 거예요. 만들며 테스트하고, 어떻게 행동하는지 지켜보고, 같은 빌드 채팅에서 다듬습니다. 에이전트가 작업하며 패널의 구성을 직접 수정하고, 모든 변경은 Build draft에 목록으로 표시됩니다. Apply를 클릭해 유지하거나 Discard로 버릴 수 있어요. 둘 중 하나를 선택하면 Build 모드를 종료하고 대화를 지웁니다.
Discard는 이 빌드 채팅의 모든 것을 버립니다 — 구성 변경과 File system의 영구 파일까지요. Build 모드에서는 구성 패널이 읽기 전용이라, 에이전트에게 바꾸고 싶은 것을 말로 알려줘야 합니다.
파일 시스템 (File System)
Build 모드에서 에이전트는 샌드박스의 실제 파일을 다룹니다 — 생성한 산출물, 스스로 설치한 프로그램, 작업 중인 모든 것요. 빌드 채팅 중 오른쪽 위의 File system을 클릭해 탐색할 수 있습니다.
빌드 채팅은 에이전트 자체를 다듬는 곳이라, 에이전트가 추가하는 것(초안한 템플릿, 설치한 도구)은 기본적으로 **Persistent(영구)**입니다. 이후 모든 대화·워크플로 실행에서 유지됩니다. 사실상 이런 파일들은 프롬프트·스킬처럼 에이전트 설정의 일부가 되는 거죠.
한 번만 필요한 작업(테스트 파일이나 한 번만 쓰는 변환기)이라면 채팅에서 "이 파일은 temporary로 유지해 줘"라고 말하세요. Temporary 아래로 가서 이 빌드 채팅이 끝나면 정리됩니다. 배포된 실행에서 에이전트가 추가하는 것은 항상 임시라서, 실행 중 무슨 일이 있어도 에이전트 자체는 바뀌지 않아요.
빌드 노트 (Build Note)
빌드 채팅에서 에이전트는 설정한 것을 빌드 노트에 기록합니다 — 처음 Apply할 때 Files에 나타나는 build_note.md예요. 노트는 에이전트 설정과 함께 저장되고, 에이전트는 새로운 대화를 시작할 때마다 노트를 다시 읽어 프롬프트와 합쳐 지시를 만듭니다.
Apply 후 빌드 노트를 열어 에이전트가 무엇을 기록했는지 확인하세요.
- 원하는 내용을 담고 있다면 그걸로 충분합니다.
- 내용을 바꾸려면 Build 모드에서 에이전트가 수정하게 하세요.
에이전트는 자동 생성된 빌드 노트 하나만 유지합니다. 다시 업로드한 다운로드본은 그냥 일반 파일일 뿐이고, 다음 빌드 채팅이 옆에 새 노트를 만듭니다.
- 빠진 게 있다면 프롬프트에 추가하세요.
- 깨끗한 기록으로 다시 시작하려면 Files에서 노트를 삭제하세요.
빌드 채팅들 사이에서 노트는 에이전트의 메모리 역할도 합니다. 한 채팅에서 회의록 에이전트를 다듬었다면, 나중에 액션 아이템 담당자를 추가하는 채팅은 처음부터가 아니라 이미 정한 형식과 결정에서 시작해요.
미리보기 (Preview)
오른쪽 패널을 Build에서 Preview로 전환하면, 배포 후 최종 사용자가 경험할 그대로 에이전트를 시험해 볼 수 있습니다 — 깔끔한 답변과 활성화된 Chat Features까지요. Preview 모드에서의 채팅은 에이전트 구성을 절대 바꾸지 않으므로, 배포 전 최종 점검으로 사용하세요.
배포 (Publish)
수정 사항은 초안으로 자동 저장됩니다. 에이전트가 준비되면 배포해 그 버전을 라이브로 만들고, 언제든 버전 히스토리를 열어 이전 버전을 다시 보거나 복원할 수 있습니다. 버전을 복원하면 에이전트 샌드박스의 영구 파일도 그 버전으로 되돌아갑니다. 웰컴 메시지, 추천 질문, 음성 같은 채팅 경험 부가 기능은 Chat Features에서 추가할 수 있고요 — 자세한 건 App Toolkit 문서를 참고하세요.
Access Point 탭에서 웹 앱으로 공유 링크에 호스팅하거나, 사이트에 임베드하거나, 서비스 API로 코드에서 호출할 수 있습니다. 에이전트를 워크플로의 Agent 노드에 초대해 한 단계를 처리하게 할 수도 있어요. 워크스페이스 간에 공유하려면 DSL 파일로 내보내세요. 스킬과 파일은 포함되지 않으니 함께 공유해야 합니다.
실행 제한 (Run Limits)
- 시간: 단일 에이전트 실행은 시작 지점(웹 앱, 서비스 API, 워크플로)과 무관하게 1시간 후 중단되고, 미완성 답변은 폐기됩니다. 실행이 끊기면 다시 시도하거나 작업을 더 작은 단계로 나누세요.
- 모델 요청: 에이전트가 모델에 하는 모든 호출은 실행당 500회 상한에 포함됩니다. 무거운 추론과 잦은 도구 사용은 더 빨리 소진시켜요. 실행을 상한 안에 두려면 작업을 더 작은 단계로 나누세요.
- 답변 파일: 답변에서 에이전트가 보내는 각 파일은 최대 50 MB이며, 그보다 큰 파일은 전달되지 않습니다.
문제 해결 (Troubleshooting)
OpenAI 호환 모델을 쓰면 에이전트가 오류를 내거나 도구를 호출하지 않습니다
OpenAI 호환 엔드포인트(vLLM 등)로 제공되는 모델은 네이티브 도구 호출 지원이 부족한 경우가 많습니다. 에이전트는 빌드 채팅과 배포 실행 모두에서 이에 의존해요. 도구 호출을 네이티브로 지원하는 모델을 고르세요. 호환 모델이 여전히 오류를 내면 제공자 설정에서 모델의 Token parameter name을 확인하세요 — 일부 최신 모델은 max_completion_tokens가 필요하고 자동 감지가 틀릴 수 있습니다. 일부 OpenAI 모델은 Chat Completions 프로토콜에서 추론(reasoning)이 활성화되면 도구 호출을 거부합니다. 그럴 땐 제공자 자격 증명의 API Protocol을 Responses API로 설정하세요.
업로드한 이미지에 에이전트가 오류를 내거나 무시합니다
Chat Features에서 이미지 업로드는 에이전트의 모델이 비전을 지원하는지와 무관하게 켤 수 있습니다. 비전 없는 모델이면 에이전트가 이미지에서 오류를 내거나 없는 것처럼 답할 수 있어요. 모델을 고를 때 Vision 태그를 찾아 비전을 지원하는 모델로 바꾸세요.
에이전트가 사내 네트워크의 파일이나 페이지를 가져오지 못합니다
에이전트의 샌드박스는 클라우드에서 실행되므로 사설 네트워크의 호스트에는 닿을 수 없습니다. 공개 URL은 동작하고, 사내 자료는 에이전트의 Files에 추가하세요.