Agent 앱 API

Agent 앱 API

여기서 Agent는 새 Agent 앱 타입(`agent` 모드)이에요. Legacy Agent 앱(`agent-chat`)은 [Chatbot and Legacy Agent](/en/api-reference/guides/chat)에서 다뤄요.

Agent 앱은 agent 모드로 돌아요. 메시지를 보내면 답변이 생성되는 대로 스트리밍되고, 여러 턴의 컨텍스트를 대화에 유지하죠.

모델이 스스로 추론하고 도구를 호출하며, 그 작업이 스트림에 그대로 드러나요. 답변 텍스트는 agent_message 이벤트로 점진적 스트리밍되고, agent_thought 이벤트가 각 추론 스텝과 도구 호출을 함께 실어 보내죠.

턴은 완성된 답변 전체를 실은 message 이벤트 하나, 그리고 message_end로 마무리됩니다. agent_message 델타를 실시간 렌더링하고, 마지막 message는 덧붙이는 게 아니라 최종 답변으로 취급하세요.

각 agent_thought 이벤트는 스텝의 thought, 호출한 tool과 tool_input, 그리고 도구의 observation을 실어 나릅니다. 전체 스트림 형태는 Send Chat Message에 있어요.

출처: 공식문서

인증, 베이스 URL, 엔드 유저 데이터를 스코프하는 `user` 필드는 [Get Started](/en/api-reference/guides/get-started)와 [End User Identity](/en/api-reference/guides/end-user-identity)에서 다뤄요.

메시지 보내고 답변 스트리밍하기

  • Send Chat Message: Agent 앱에 쿼리를 보냅니다. 스트리밍 모드만 지원하고, blocking 모드는 400 bad_request 오류가 나요.

    답변 텍스트는 토큰 단위가 아니라 대략 0.5초 간격으로 배치된 agent_message 델타로 스트리밍돼요.

    마지막 message_end 이벤트가 토큰 사용량을 보고해요. 지식 검색 인용(retriever_resources)은 절대 포함하지 않아요.

    두 가지 한도가 실행을 일찍 끝낼 수 있고, 둘 중 어느 쪽이든 agent_run_limit_exceeded 오류 코드로 스트림을 닫아요:

    • 시간: 기본적으로 실행은 1시간 뒤에 멈춥니다.

      셀프호스트에서 더 긴 실행이 필요하다면 APP_MAX_EXECUTION_TIME, WORKFLOW_MAX_EXECUTION_TIME, DIFY_AGENT_RUN_TIMEOUT_SECONDS를 필요한 시간 위로 올리세요. 자세한 내용은 Environment Variables를 보세요.

    • 모델 요청: 각 실행은 500회로 상한이 정해져 있어요.

  • Stop Chat Message Generation: 끝나기 전에 스트리밍 답변을 중단합니다.

  • Get Next Suggested Questions: 답변이 끝난 뒤 지금까지의 대화를 바탕으로 후속 질문을 제안해요.

대화 관리하기

  • List Conversations: 현재 유저의 대화를 최근 활동 순으로 나열해요.
  • List Conversation Messages: 대화 하나의 메시지 기록. 스크롤하는 채팅 UI를 위해 써요. 각 메시지의 agent_thoughts 배열이 그 턴의 추론 스텝을 실어요.
  • Rename Conversation: 대화 이름을 설정하거나 내용에서 생성해요.
  • Delete Conversation: 대화와 그 메시지를 제거해요.

파일 업로드하기

  • Upload File: 이미지·문서·오디오·비디오 파일을 업로드하고, 업로드한 엔드 유저에게 스코프됩니다.

    Send Chat Message에 넘긴 파일은 에이전트가 샌드박스에서 가져와 조사할 수 있는 다운로드 참조로 노출돼요.

  • Get End User Info: 엔드 유저 ID(Upload File 응답의 created_by 같은 것)로 세부 정보를 조회해요.

음성을 텍스트로, 텍스트를 음성으로

  • Convert Audio to Text: 업로드한 오디오(MP3·M4A·WAV·AMR·MPGA, 최대 30MB)를 받아쓰기해, 엔드 유저가 타이핑 대신 말로 입력하게 해줘요.
  • Convert Text to Audio: 답변을 다시 음성으로 합성해요.

앱 정보와 설정 가져오기

  • Get App Info: 앱의 이름, 설명, 태그, 모드.
  • Get App Parameters: 호출이 inputs로 보내는 필드(이름·타입·기본값)와 앱의 기능 스위치—요청이나 클라이언트 UI를 만들 때의 기반이 돼요.
  • Get App Meta: 앱 메타데이터. Agent 앱에서는 tool_icons 맵이 비어 있어요.
  • Get App WebApp Settings: 웹 앱의 사이트 설정, 테마, 커스터마이즈 옵션.

더 알아보기 (Learn more)