对话与异步 Turn 集成

当业务需要保留多轮会话、读取结构化引用证据、处理写操作确认或导出 PDF 报告时,使用原生 Chat / Turn API。只需要标准流式文本时,可直接用 OpenAI 兼容接口。

异步 Turn 生命周期

在 ApeMind 中,一次问答被建模为异步执行的 Turn:创建请求立即返回 turn_id,后台 Agent 节点完成多轮检索、工具调用与生成后将状态推进到终态。这种设计让客户端断开重连不会中断长任务,也允许随时取消或响应人工确认。

  1. 创建会话(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')
  2. 提交 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')
  3. 获取结果(轮询或 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
  4. 按需取消

    客户端主动断开连接不会取消后台执行。要真正中止任务,显式调用取消接口并轮询到取消终态:

    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 分发渲染:

交互钩子:写确认、补充信息与追问

当 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 的多轮提问中反复引用:

2. PDF 异步导出(24h TTL)vs Chat JSONL 导出

系统提供两种完全不同的导出流程,切勿混用:

3. 冻结分享快照与显式撤销

通过 POST /api/v2/bots/{agent_id}/chats/{chat_id}/share 或 .../turns/{turn_id}/share 生成的公开链接,指向创建时刻冻结的对话快照——后续继续对话或删除原会话都不会改动快照内容。

删除 Chat 或 Agent 不会自动撤销分享

任何持有分享 Token 的匿名访客都可以读取已生成的快照。测试或业务下线时,必须记录 share_id 并显式调用撤销接口,再匿名验证返回 404。如果要让外部用户直接与 Agent 实时对话(而非看冻结快照),请使用公开链接与网站嵌入。

下一步