异步 Turn 生命周期
在 ApeMind 中,一次问答被建模为异步执行的 Turn:创建请求立即返回 turn_id,后台 Agent 节点完成多轮检索、工具调用与生成后将状态推进到终态。这种设计让客户端断开重连不会中断长任务,也允许随时取消或响应人工确认。
-
创建会话(Chat)
路径沿用历史命名
/bots/{agent_id}/chats。普通业务调用不要设置peer_type=evaluation,否则会话会从常规列表中隐藏。CHAT_ID=$(curl -fsS \ -X POST "${APEMIND_BASE_URL}/api/v2/bots/${AGENT_ID}/chats" \ -H "Authorization: Bearer ${APEMIND_API_KEY}" | jq -r '.id') -
提交 Turn(带幂等键)
每次新提问生成唯一的
client_idempotency_key(如 UUID)。网络超时重试时复用同一个键,服务端返回原 Turn 而不重复生成回答;切勿为不同的问题复用同一个幂等键。TURN_ID=$(curl -fsS \ -X POST "${APEMIND_BASE_URL}/api/v2/agent/chats/${CHAT_ID}/turns" \ -H "Authorization: Bearer ${APEMIND_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "query": "合同在哪些情况下可以解除?", "collections": [{"id": "'"${KB_ID}"'", "title": "合同知识库", "mode": "advisory"}], "attachments": [], "web_search_enabled": false, "language": "zh-CN", "client_idempotency_key": "contract-q-20261122-001" }' | jq -r '.turn.turn_id') -
获取结果(轮询或 SSE)
使用 API Key 时轮询快照接口直到终态;使用浏览器会话或 Desktop OAuth 时可订阅 SSE 事件流。也可以直接用 CLI 阻塞等待终态:
# API Key 轮询快照 curl -fsS \ -H "Authorization: Bearer ${APEMIND_API_KEY}" \ "${APEMIND_BASE_URL}/api/v2/agent/chats/${CHAT_ID}/turns/${TURN_ID}" # 或用 CLI 等待完成并输出结构化结果 apemind turn wait "${TURN_ID}" --chat-id "${CHAT_ID}" --workspace "${APEMIND_ORG_ID}" --timeout 10m -
按需取消
客户端主动断开连接不会取消后台执行。要真正中止任务,显式调用取消接口并轮询到取消终态:
curl -fsS -X POST \ -H "Authorization: Bearer ${APEMIND_API_KEY}" \ "${APEMIND_BASE_URL}/api/v2/agent/chats/${CHAT_ID}/turns/${TURN_ID}/cancel"
SSE 事件流与轮询的鉴权差异
原生事件流 GET /api/v2/agent/chats/{chat_id}/turns/{turn_id}/events?after_sequence=0(Accept: text/event-stream)与快照轮询的鉴权范围不同,集成前先核对下表:
| 调用凭据 | Turn 快照轮询 | 原生 SSE 事件流 | 备选流式方案 |
|---|---|---|---|
| 组织 / 成员 / Agent API Key | 支持 | 不支持(返回 403) |
使用 OpenAI 兼容流式端点 |
| Desktop OAuth Token | 支持 | 支持(需申请 turn.read + workspace.read,并带 X-ApeMind-Workspace-Id) |
— |
| 浏览器 Cookie 会话 | 支持 | 支持(不能与 API Key 同时发送) | — |
断线重连 SSE 时,将客户端收到的最后一个事件序号传给 after_sequence,服务端从断点续传,避免重放全量时间线。不要把响应中的 stream_url 当作无需鉴权的公开链接。
解析 parts[] 与证据
Turn 快照不会把所有内容拼成单一字符串,而是按执行顺序返回结构化 parts[] 数组,调用方应按 parts[].type 分发渲染:
- 文本与推理:最终回答正文与可选思考摘要;失败 Turn 应读取
error_text,不要把中途残缺的文本片段当作完整回答。 - 工具调用与来源引用:包含检索工具调用轨迹、命中片段与可溯源的原文引用坐标。完整字段字典见 API 参考。
timeline_cursor:当前快照覆盖到的最新事件序号,可与事件流无缝衔接。
交互钩子:写确认、补充信息与追问
当 Agent 配置了 policy.write_confirmation: true、调用带审批策略的外部连接,或开启了 policy.ask_user: true 时,Turn 在运行中会暂停并发出交互事件。调用方收到对应 ID 后通过以下接口恢复执行:
| 交互类型 | 触发场景 | 提交端点 / CLI |
|---|---|---|
工具确认(consent) |
沙箱写操作或高风险外部连接调用等待人工批准 | POST /api/v2/agent/chats/{chat_id}/turns/{turn_id}/consent/{tool_call_id}apemind turn consent TURN_ID --chat-id CHAT_ID --tool-call-id ID --decision approved|denied |
结构化补充(elicit) |
工具或技能需要结构化表单参数 | POST /api/v2/agent/chats/{chat_id}/turns/{turn_id}/elicit/{elicitation_id}apemind turn elicit TURN_ID --chat-id CHAT_ID --elicitation-id ID --input response.json |
向用户追问(ask_user) |
需求存在歧义时 Agent 主动发问,用户回答后继续当前轮次 | 按快照中的追问提示回复;在无界面评测与定时任务会话中,服务端会自动禁用交互等待避免空等超时 |
重复提交、超时过期或不属于当前 Turn 的 ID 会被服务端拒绝;OAuth 客户端调用写交互需要 turn.write 权限。
必须了解的三条非显而易见规则
1. 附件生命周期与沙箱挂载
通过 POST /api/v2/chats/{chat_id}/attachments 上传的附件严格归属当前 Chat,不能跨 Chat 复用,但可以在本 Chat 的多轮提问中反复引用:
- 解析状态:可提取文字的类型(PDF、Office、图片 OCR 等)后台异步从
processing进入ready;压缩包、代码或二进制文件直接为ready且content_extracted: false,仍可供 Agent 在沙箱中处理。 - 上下文与读取:本轮附件在预算内直接注入上下文(单文件 16k、整轮 32k 字符),超出部分由 Agent 通过
read_attachment按需分页检索。 - 代码模式沙箱:Agent 开启
workspace后,Chat 附件会在每轮开始时自动同步到沙箱/workspace/uploads/<文件名>(仅补齐缺失文件,不覆盖 Agent 已改写的文件;单轮上限 30 秒 / 1 GiB)。如需访问沙箱内生成的文件,见 API 参考 中的 Workspace Files 接口。 - 转存知识库:调用
POST /api/v2/chats/{chat_id}/attachments/{attachment_id}/promote可将临时附件转为持久知识库文档。
2. PDF 异步导出(24h TTL)vs Chat JSONL 导出
系统提供两种完全不同的导出流程,切勿混用:
- Turn PDF 导出(异步,产物 24h 过期):调用
POST /api/v2/agent/chats/{chat_id}/turns/{turn_id}/exports(必填format: "pdf"与合法 IANA 时区user_timezone,如"Asia/Shanghai")返回202与export_task_id;轮询GET /api/v2/turn-exports/{id}变为COMPLETED后下载。没有客户端删除接口,只有COMPLETED产物适用约 24 小时 TTL,过期后下载返回410、任务行保留为EXPIRED,如需再次获取请重新提交。 - Chat JSONL 导出(同步,安全投影
chat-export-v1):调用GET /api/v2/bots/{agent_id}/chats/{chat_id}/export。每条记录的question已由服务端安全投影为可读标题(如@知识库标题),contexts[]只包含{kind, title},不含内部对象 ID 或私有链接;调用方无需自行清洗 token。
3. 冻结分享快照与显式撤销
通过 POST /api/v2/bots/{agent_id}/chats/{chat_id}/share 或 .../turns/{turn_id}/share 生成的公开链接,指向创建时刻冻结的对话快照——后续继续对话或删除原会话都不会改动快照内容。
任何持有分享 Token 的匿名访客都可以读取已生成的快照。测试或业务下线时,必须记录 share_id 并显式调用撤销接口,再匿名验证返回 404。如果要让外部用户直接与 Agent 实时对话(而非看冻结快照),请使用公开链接与网站嵌入。