Session 与 Turn
后端使用 Organization API Key,并在路径中指定拥有该 Session 的 End User。保留的 User Key 读写操作使用自己的 /api/v1/user/sessions 路径。
创建和读取会话
Section titled “创建和读取会话”| 方法与路径 | 用途 |
|---|---|
POST /api/v1/org/users/{userId}/sessions |
从指定 AgentTemplate 创建 Session,冻结当前配置。 |
GET /api/v1/org/users/{userId}/sessions |
按游标分页列出指定 End User 的 Session。 |
GET /api/v1/org/users/{userId}/sessions/{id} |
读取元信息和当前执行标识。 |
PATCH /api/v1/org/users/{userId}/sessions/{id}/model |
使用 Session 的 If-Match token 选择下一 Turn 的模型。 |
POST /api/v1/org/users/{userId}/sessions/{id}/name |
设置显示名称。 |
DELETE /api/v1/org/users/{userId}/sessions/{id} |
在执行和清理边界内隐藏 Session。 |
创建接受 { "agentTemplateId": "…", "model": "…" },省略 model 时使用当前发布版本提供的默认模型,未提供时使用组织默认模型。模型选择属于 Session,独立于模板行为。切换时向模型接口提交 { "model": "…" },并把读取 Session 返回的 ETag 放入 If-Match。缺少或过期 token 分别返回 428 和 412。可选模型仅限当前发布版本提供的模型。执行中切换从下一 Turn 生效,引导和续执行保留当前 Turn 接纳时的模型。
后续的模板保存影响新建 Session。已有 Session 保留固定配方,执行仍受当前权限和依赖可用性约束。隐藏会话与清除历史是不同操作。
创建时使用稳定的 Idempotency-Key。可同时传入 additionalInstructions 和 sandbox。目标模板启用跨会话 Recall 时,显式传入 acknowledgeSessionRecall: true。Session 列表可用 agentTemplateId 按当前 Configuration Epoch 筛选。已保存的 Turn 记录准入时的 agentTemplateId。
切换 Session 的 Template
Section titled “切换 Session 的 Template”向 POST /api/v1/org/users/{userId}/sessions/{id}/template-switches 发送目标 agentTemplateId 和稳定的 Idempotency-Key。Session 必须空闲,且没有活动 Realtime Connection。目标模板启用跨会话 Recall 时须确认。重放同一请求可查询原命令的最新回执。
有已纳入历史的 Session 返回 pending 回执和 handoffTurnId。历史中的 template_handoff Turn 只有成功后的 assistant Message,可用该 Turn ID 读取摘要。成功会启用新的 Configuration Epoch,失败或取消保留原 Epoch,并留下终态 Turn。没有已纳入历史的 Session 可直接切换。等效配置返回 unchanged。
POST /api/v1/org/users/{userId}/sessions/{id}/events 接纳消息、显式取消,以及部署启用后的检查点重试,可靠接纳后返回稳定 JSON 命令回执。提交与跟进分离:应用服务器通过其 Backend Connection 跟进 Session 事件,其他客户端读取回执、Turn 和时间线。
Turn 检查点重试默认关闭。关闭或不可用时,新的 InputRetryEvent 返回 400 checkpoint_runtime_unavailable。启用后,若目标 Turn 属于更早的 Session Configuration Epoch,新的重试返回 409 session_configuration_epoch_changed。已受理重试命令的精确重放仍以 200 恢复原回执,不会再次执行;关闭重试不会移除已保存的历史,也不会禁用取消操作。
一个 Session 最多有一个活动 Full Agent Turn;已完成的 Realtime Turn 不占用该名额。执行中的新纯文本要求引导同一个 Turn,不排队创建下一轮。接纳本身不能证明实际并入或执行成功。取消记录停止意图,需要读取最终结果。已经完成的外部效果保持其实际影响。
恢复不确定请求时保留原命令身份和内容。查询原回执不会再次提交或执行命令。显式检查点重试属于新命令,其结果应与之前执行的结果区分。
读取回执与历史
Section titled “读取回执与历史”| 方法与路径 | 用途 |
|---|---|
GET /api/v1/org/users/{userId}/sessions/{id}/interactions |
分页读取消息、取消和检查点重试回执,或按原命令键找回原重试回执。 |
GET /api/v1/org/users/{userId}/sessions/{id}/interactions/{receiptId} |
读取原命令及原次执行结果。 |
GET /api/v1/org/users/{userId}/sessions/{id}/turns |
按游标分页读取 Full Agent Turn 和有用户输入的 Realtime Turn。 |
GET /api/v1/org/users/{userId}/sessions/{id}/turns/{turnId} |
读取指定 Full Agent Turn 或有用户输入的 Realtime Turn 的已保存历史。 |
GET /api/v1/org/users/{userId}/sessions/{id}/timeline |
按 Session 时间线顺序分页读取 Turn 与 Realtime 事实。 |
POST /api/v1/org/users/{userId}/sessions/{id}/turns/audio |
在适用接纳规则下转写音频并提交 Turn。 |
原次执行结果以命令回执为准。当前 Turn 状态与 Session 是否空闲回答不同的问题。成功的 assistant Message、部分草稿和进度信息含义不同;失败草稿不是最终答案。
Session 事件与恢复说明如何跟进持久事件与重连。
转写元数据、无用户输入的播报和分页行为见读取 Realtime 对话历史。