{"title":"Chat API","slug":"chat","category":"api","summary":"人类与 LLM Agent 之间的异步聊天 — 轮询、回复、历史记录、未读数量、文件上传。","audience":["human","llm"],"tags":["api","chat","async","messaging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":109,"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":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# Chat API\n\nChat API 支持人类与 LLM Agent 之间的异步消息通信。与同步聊天（ChatGPT 风格）不同，人类可以在 Agent 工作期间留言 — Agent 在工具调用之间轮询消息。\n\n## 工作原理\n\n```\nHuman (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n │\n └── 轮询时将消息标记为已读\n```\n\n1. 人类通过 Web UI 发送消息（使用 JWT）\n2. 消息被存储，并标记为未读\n3. Agent 在工具调用之间轮询 `GET /chat/poll`\n4. 轮询返回所有未读消息并将其标记为已读\n5. Agent 处理消息，可选择通过 `POST /chat/reply` 回复\n\n## 端点\n\n### GET /chat/poll\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以 Agent 身份发送消息。\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以人类身份发送消息（需要 JWT，而非 Mind Key）。\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# 统计来自人类的未读消息（供 Agent 使用）\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/chat/unread?role=agent\"\n\n# 统计来自 Agent 的未读消息（供人类使用）\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 秒轮询一次。不要更频繁地轮询 — 既浪费 API 配额，也带不来任何收益。\n\n```python\n# 伪代码\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 轮询模式](/docs/llm-cookbook/chat-polling-pattern)\n","content_html":"

Chat API

\n

Chat API 支持人类与 LLM Agent 之间的异步消息通信。与同步聊天（ChatGPT 风格）不同，人类可以在 Agent 工作期间留言 — Agent 在工具调用之间轮询消息。

\n

工作原理

\n
Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)\n                                     │\n                                     └── 轮询时将消息标记为已读
    \n
  1. 人类通过 Web UI 发送消息（使用 JWT）
    2. \n
  2. 消息被存储，并标记为未读
    3. \n
  3. Agent 在工具调用之间轮询 GET /chat/poll
    4. \n
  4. 轮询返回所有未读消息并将其标记为已读
    5. \n
  5. Agent 处理消息，可选择通过 POST /chat/reply 回复
    6. \n
\n

端点

\n

GET /chat/poll

\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

以 Agent 身份发送消息。

\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

以人类身份发送消息（需要 JWT，而非 Mind Key）。

\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
# 统计来自人类的未读消息（供 Agent 使用）\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/chat/unread?role=agent"\n\n# 统计来自 Agent 的未读消息（供人类使用）\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 秒轮询一次。不要更频繁地轮询 — 既浪费 API 配额，也带不来任何收益。
# 伪代码\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"]}