{"title":"Chat API","slug":"chat","category":"api","summary":"사람과 LLM 에이전트 간의 비동기 채팅 — 폴링, 응답, 기록, 읽지 않은 메시지 수, 파일 업로드.","audience":["human","llm"],"tags":["api","chat","async","messaging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":208,"read_minutes":1,"llm_context":"Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)\nPoll: GET /chat/poll (returns unread messages, marks them as read)\nReply: POST /chat/reply { content }\nHistory: GET /chat/history?limit=50\nUnread count: GET /chat/unread?role=agent (or ?role=human)\nUpload: POST /chat/upload (multipart, file attachment)\nPattern: poll between tool calls, reply when human asks questions\n","lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# Chat API\n\nChat API는 사람과 LLM 에이전트 간의 비동기 메시징을 지원합니다.\n동기식 채팅(ChatGPT 스타일)과 달리, 사람은 에이전트가 작업 중인 동안에도\n메시지를 남길 수 있으며 — 에이전트는 도구 호출 사이에 폴링합니다.\n\n## 작동 방식\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── marks messages as read on poll\n```\n\n1. 사람이 웹 UI를 통해 메시지를 전송합니다 (JWT 사용)\n2. 메시지가 저장되고 읽지 않음으로 표시됩니다\n3. 에이전트는 도구 호출 사이에 `GET /chat/poll`을 폴링합니다\n4. 폴링은 모든 읽지 않은 메시지를 반환하고 읽음으로 표시합니다\n5. 에이전트는 메시지를 처리하고, 선택적으로 `POST /chat/reply`로 응답합니다\n\n## 엔드포인트\n\n### GET /chat/poll\n\n사람이 보낸 새 메시지를 폴링합니다. 읽지 않은 메시지를 반환하고 읽음으로\n표시합니다. 도구 호출 사이에 사용하십시오.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/poll\n```\n\n응답:\n\n```json\n{\n \"messages\": [\n {\n \"id\": \"msg_001\",\n \"role\": \"human\",\n \"content\": \"How's the deployment going?\",\n \"created_at\": \"2026-06-27T...\"\n }\n ]\n}\n```\n\n### POST /chat/reply\n\n에이전트로 메시지를 전송합니다.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/reply \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Deployment is 80% done. CI is green, just waiting for Docker push.\"}'\n```\n\n### POST /chat/send\n\n사람으로 메시지를 전송합니다 (Mind Key가 아닌 JWT 필요).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/send \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Can you check the logs?\"}'\n```\n\n### GET /chat/history\n\n최근 채팅 기록을 가져옵니다 (양쪽 역할 모두).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/history?limit=50\"\n```\n\n### GET /chat/unread\n\n읽지 않은 메시지 수를 가져옵니다.\n\n```bash\n# Count unread messages from human (for agent)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# Count unread messages from agent (for human)\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=human\"\n```\n\n### GET /chat/status\n\n채팅 세션 상태를 가져옵니다 (마지막 메시지 타임스탬프, 읽지 않은 메시지 수).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/chat/status\n```\n\n### POST /chat/upload\n\n특정 메시지의 파일 첨부를 업로드합니다 (multipart 폼).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/chat/upload \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -F \"message_id=msg_001\" \\\n -F \"file=@screenshot.png\"\n```\n\n### GET /chat/files/:message_id\n\n메시지의 파일 첨부 목록을 조회합니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/files/msg_001\n```\n\n### GET /chat/file/:file_id\n\n파일 첨부를 다운로드합니다.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/chat/file/file_001 --output download.png\n```\n\n## 폴링 패턴\n\n> [!TIP]\n> 도구 호출 사이에 30-60초마다 폴링하십시오. 더 자주 폴링하지 마십시오 —\n> API 할당량을 낭비하고 이점이 없습니다.\n\n```python\n# Pseudo-code\nwhile working:\n messages = poll_chat()\n for msg in messages:\n process_message(msg)\n reply(f\"Acknowledged: {msg.content}\")\n do_one_tool_call()\n```\n\n## 다음 단계\n\n- [Tasks API](/docs/api/tasks)\n- [Chat Polling Pattern](/docs/llm-cookbook/chat-polling-pattern)\n","content_html":"

Chat API

\n

Chat API는 사람과 LLM 에이전트 간의 비동기 메시징을 지원합니다.\n동기식 채팅(ChatGPT 스타일)과 달리, 사람은 에이전트가 작업 중인 동안에도\n메시지를 남길 수 있으며 — 에이전트는 도구 호출 사이에 폴링합니다.

\n

작동 방식

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── marks messages as read on poll
    \n
  1. 사람이 웹 UI를 통해 메시지를 전송합니다 (JWT 사용)
    2. \n
  2. 메시지가 저장되고 읽지 않음으로 표시됩니다
    3. \n
  3. 에이전트는 도구 호출 사이에 GET /chat/poll을 폴링합니다
    4. \n
  4. 폴링은 모든 읽지 않은 메시지를 반환하고 읽음으로 표시합니다
    5. \n
  5. 에이전트는 메시지를 처리하고, 선택적으로 POST /chat/reply로 응답합니다
    6. \n
\n

엔드포인트

\n

GET /chat/poll

\n

사람이 보낸 새 메시지를 폴링합니다. 읽지 않은 메시지를 반환하고 읽음으로\n표시합니다. 도구 호출 사이에 사용하십시오.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/chat/poll

응답:

\n
{\n  "messages": [\n    {\n      "id": "msg_001",\n      "role": "human",\n      "content": "How's the deployment going?",\n      "created_at": "2026-06-27T..."\n    }\n  ]\n}

POST /chat/reply

\n

에이전트로 메시지를 전송합니다.

\n
curl -X POST https://synapse.schaefer.zone/chat/reply \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Deployment is 80% done. CI is green, just waiting for Docker push."}'

POST /chat/send

\n

사람으로 메시지를 전송합니다 (Mind Key가 아닌 JWT 필요).

\n
curl -X POST https://synapse.schaefer.zone/chat/send \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Can you check the logs?"}'

GET /chat/history

\n

최근 채팅 기록을 가져옵니다 (양쪽 역할 모두).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/history?limit=50"

GET /chat/unread

\n

읽지 않은 메시지 수를 가져옵니다.

\n
# Count unread messages from human (for agent)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/unread?role=agent"\n\n# Count unread messages from agent (for human)\ncurl -H "Authorization: Bearer YOUR_JWT" \\\n     "https://synapse.schaefer.zone/chat/unread?role=human"

GET /chat/status

\n

채팅 세션 상태를 가져옵니다 (마지막 메시지 타임스탬프, 읽지 않은 메시지 수).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/chat/status

POST /chat/upload

\n

특정 메시지의 파일 첨부를 업로드합니다 (multipart 폼).

\n
curl -X POST https://synapse.schaefer.zone/chat/upload \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -F "message_id=msg_001" \\\n  -F "file=@screenshot.png"

GET /chat/files/:message_id

\n

메시지의 파일 첨부 목록을 조회합니다.

\n
curl -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/chat/files/msg_001

GET /chat/file/:file_id

\n

파일 첨부를 다운로드합니다.

\n
curl -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/chat/file/file_001 --output download.png

폴링 패턴

\n
도구 호출 사이에 30-60초마다 폴링하십시오. 더 자주 폴링하지 마십시오 —\nAPI 할당량을 낭비하고 이점이 없습니다.
# Pseudo-code\nwhile working:\n    messages = poll_chat()\n    for msg in messages:\n        process_message(msg)\n        reply(f"Acknowledged: {msg.content}")\n    do_one_tool_call()

다음 단계

\n\n","urls":{"html":"/docs/api/chat","text":"/docs/api/chat?format=text","json":"/docs/api/chat?format=json","llm":"/docs/api/chat?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}