Octop 对话 API：WebSocket 流式传输与线程管理

通过 WebSocket 与 Octop 专家对话并流式接收回复，并使用线程管理端点组织对话历史。

通过 WebSocket 与专家对话，实时流式接收回复，并管理对话线程。

​

WebSocket 端点

WS /api/agents/{id}/chat/ws?token=<jwt>

由于浏览器 WebSocket API 不支持自定义头，令牌需作为查询参数传递，而不是 Authorization 头。

​

消息帧

向专家发送一轮对话：

{"type": "user_turn", "content": "你好！", "thread_id": "abc123"}

服务器以流式块回应：

{"type": "chunk", "content": "你好！我能"}

回复完成时发送：

{"type": "done"}

若发生错误：

{"type": "error", "message": "模型请求超时"}

为保持连接存活，可发送 ping/pong 帧：

{"type": "ping"}

{"type": "pong"}

断线本身不会取消正在进行的回合。重连后发送 subscribe 可挂接到仍在流式输出的线程；服务器以 turn_status 回应：

{"type": "subscribe", "thread_id": "abc123"}

{"type": "turn_status", "thread_id": "abc123", "active": true}

显式停止当前回合：

{"type": "cancel", "thread_id": "abc123"}

thread_id 在整个对话中保持不变。若需在断开后恢复会话，请使用创建线程时返回的 session_key。页面刷新后先拉 history，根据 turn_active 再决定是否 subscribe。

​

线程管理

方法	路径	描述
GET	/agents/{id}/chat/sessions	列出对话线程
POST	/agents/{id}/chat/sessions	创建新线程
PATCH	/agents/{id}/chat/sessions/{thread_id}	重命名或固定线程
DELETE	/agents/{id}/chat/sessions/{thread_id}	删除线程
GET	/agents/{id}/chat/sessions/{thread_id}/history	获取线程历史记录（含 turn_active）
GET	/agents/{id}/threads/{thread_id}/trajectory	分页运行轨迹摘要，用 before_seq 取更早记录
GET	/agents/{id}/threads/{thread_id}/trajectory/events/{event_id}	单条事件完整载荷
GET	/agents/{id}/threads/{thread_id}/trajectory/metrics	回合、耗时与 token 汇总
GET	/agents/{id}/threads/{thread_id}/trajectory/stream	实时 SSE，用 after_seq 或 Last-Event-ID 续传
GET	/agents/{id}/threads/{thread_id}/trajectory/export	导出账本，默认 JSONL，也可 JSON

​

创建线程

curl -X POST http://127.0.0.1:8088/api/agents/1/chat/sessions \
  -H 'Authorization: Bearer <token>'

响应：

{"thread_id": "abc123", "session_key": "sk_..."}

​

获取历史记录

curl "http://127.0.0.1:8088/api/agents/1/chat/sessions/abc123/history?limit=50&offset=0" \
  -H 'Authorization: Bearer <token>'

支持 limit 和 offset 分页参数。响应还包含布尔字段 turn_active：为 true 时，请重新打开聊天 WebSocket 并发送 {"type":"subscribe","thread_id":"..."} 以恢复流式输出。

​

重命名或固定线程

curl -X PATCH http://127.0.0.1:8088/api/agents/1/chat/sessions/abc123 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"title": "项目规划讨论", "pinned": true}'

​

润饰端点

在实际发送之前优化用户输入的提示词文本：

curl -X POST http://127.0.0.1:8088/api/agents/1/chat/polish \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"text": "帮我写个邮件"}'

响应：

{"text": "请帮我草拟一封专业的邮件，受信人是..."}

可选参数 default_model 可用于覆盖润饰时使用的模型。

​

分叉会话

POST /api/agents/{id}/threads/{thread_id}/fork 把一段对话复制成新线程，截止到指定的专家回复。原对话不变。传 assistant_turns_from_end: 1 可从最新一条回复分叉，或传入 message_id。专家需要处于运行中。

​

文件与知识库引用

线程列表和历史会带上专家生成的文件（例如写文件、桌面截图），以及回复用到知识库时的来源文档。页面里点击引用可在聊天中预览文档。

​

运行轨迹

GET /agents/{id}/threads/{thread_id}/trajectory* 对应聊天里的运行轨迹抽屉：分页事件摘要、单条完整事件、汇总指标、实时 SSE 和导出。需要审计回合与工具调用时用这些接口，不必刮页面。

润饰端点很适合用于 UI 中的“润饰提示词”按钮——在实际发射前帮用户把输入润色为更清晰、更具体的提示词。