Session 事件与恢复
通过 Session 的 events 路径以 POST 提交命令。可靠接纳的命令返回 JSON 回执,执行与该响应相互独立。跟进执行的方式取决于你的集成:
- 持有 Organization API Key 的应用服务器(Application Server)通过其 Backend Connection 接收该 Session 的持久事件。
- 没有 Backend Connection 的客户端(例如持有 User API Key 的客户端)读取回执、Turn 和时间线。
- 音频 Turn 自身的响应以 Server-Sent Events(SSE)流式返回该 Turn。
不存在按 Session 订阅事件的接口。
通过 Backend Connection 跟进事件
Section titled “通过 Backend Connection 跟进事件”Backend Connection 是从你的应用服务器进程到 /api/v1/org/backend/ws 的一条 WebSocket,使用 tidb-link.backend.v1 子协议,并在 Authorization 请求头中携带 Organization API Key;其消息见 API 参考。用 session.attach 挂接 Session,传入其 End User 的 userId、sessionId,重连后还要传入最后处理的事件的 cursor。核心先重放该游标之后的事件,再把每个新事件作为带有自身 cursor 的 session.event 发送。同一 Session 的事件按顺序到达,不缺失也不重复。
读取草稿快照
Section titled “读取草稿快照”每个 session.event 包含 JSON 信封,字段为 type、sessionId、turnId、createdAt 和 data。对 agent.session.turn.* 类型,内层 data 是已保存的 Turn 事件;agent.session.realtime.* 类型携带 Session 时间线中的一条 Realtime 事实,其 turnId 可能为 null,字段见 API 参考。按信封的类型区分答案草稿与进度消息:
const drafts = new Map();function receive(envelope) { if (envelope.type === 'agent.session.turn.output_text.snapshot') { drafts.set(envelope.turnId, envelope.data.payload.text); }}快照包含该 Turn 到目前为止的完整临时草稿。替换显示的草稿;追加会造成重复文字。后续快照可以修改此前文字,也可以用空字符串清空草稿。按 turnId 分别保存各 Turn 的草稿。重新挂接后的首条快照不依赖此前的草稿帧。agent.session.turn.progress 在 data.payload.text 中携带独立的进度消息,不更新答案。不提供 output_text.delta 别名。
最终保存的助手消息通过 agent.session.turn.item.added 到达,其中 data.event 为 assistant_message,正文与消息身份分别在 data.payload.text 和 data.payload.messageId 中。用 Turn 的终态事件判断成功、失败或取消。音频入口 POST /turns/audio 接受 multipart 上传,直接返回 SSE;每帧的事件名对应 Turn 事件,data 包含该事件的 JSON。执行期间关闭音频响应会请求中断。
没有 Backend Connection 时读取结果
Section titled “没有 Backend Connection 时读取结果”用 /interactions/{receiptId} 读取回执,再用 /turns/{turnId} 读取回执中 turnId 指向的 Turn,直到其 status 不再是 running。读取运行中的 Turn 得到的是其目前进度的快照。/timeline 按同一顺序列出 Turn 与 Realtime 事实。
等待空闲事件
Section titled “等待空闲事件”Turn 的终态事件和命令结果会在 Session 释放该 Turn 之前稍早保存。在此之前,下一条消息会并入或被已结束的 Turn 拒绝,音频 Turn 或 Template 切换会返回 409。agent.session.idle 表示释放已经发生。发送下一条消息、音频 Turn 或 Template 切换前,先等待该事件。其 data 为 { id, turnId, createdAt },turnId 指被释放的 Turn;该 Turn 从未保存时为 null。租约过期后由恢复中断的 Turn 同样会先保存终态事件。空闲事件不说明 Turn 的结果,同一 Turn 之后可能出现多次;存在进行中的 Realtime Connection 时,Template 切换仍会返回 409。没有 Backend Connection,或需要限定等待时间时,读取 Session 并确认 activeTurnId 为 null。对音频入口,其响应结束即为空闲点。
连接生命周期
Section titled “连接生命周期”关闭 Backend Connection 或 POST /events 命令响应都不会取消已接纳的执行;音频 Turn 运行期间关闭其响应会请求中断。取消必须通过 POST events 显式提交命令。预算、超时和主动停止仍限制执行。
跟进只负责观察:没有挂接的连接、读取较慢或断线都不会取消 Turn。保留最后的事件游标,以便重连后重新挂接并继续。撤销或轮换连接使用的 Organization API Key,或停用其 Organization,都会关闭其 Backend Connection,且不会取消 Turn。
单独恢复命令
Section titled “单独恢复命令”用 GET /api/v1/user/sessions/{id}/interactions 找回原命令回执,用 /interactions/{receiptId} 读取原次结果;用 /turns 和 /turns/{turnId} 读取包含 Realtime Turn 的对话历史,用 /timeline 按同一顺序读取 Turn 与 Realtime 事实。查询回执不会再次运行。
保留原命令身份和内容,按回执匹配对应执行,区分进度与原次最终结果。EOF、agent.session.idle 事件或命令已接纳都不能证明成功。执行成功前,部分草稿仍是临时内容。
Session 与 Turn列出命令和历史端点。
转写元数据、无用户输入的播报和分页行为见读取 Realtime 对话历史。