Skip to main content
Conversation 表示用户与 Agent 的持续上下文；Run 表示其中一条用户消息触发的执行。继续对话时复用 conversation_id，订阅或取消某次执行时使用 run_id。

​
新建与继续

首次启动时省略 conversation_id：
保存响应中的 conversation_id。后续消息继续该会话：
会话与项目绑定。不能把项目 A 的 conversation_id 用在项目 B 的路径中，也不能通过会话 ID 绕过项目权限。 省略 skills 时，继续会话会继承该会话保存的用户 Skill 选择；详细规则见 附件与 Skills。模型、性能档位和禁云参数按下表分别处理；内部 mode、MCP 配置和 Web 端扩展字段仍不可通过 OpenAPI 覆盖。

​
配置继承规则

上述“下一次 Run”与“同一 Run 恢复”不同：回复 Action、工具或进程恢复、上下文压缩不会创建一次新的外部启动请求，应沿用该 Run 已保存的配置。禁云策略也会传给该 Run 的子 Agent。 前面的最小继续会话示例省略了模型、档位和禁云参数，因此使用当前默认模型、standard 和 disable_cloud: false。若希望延续上次选择，请显式补齐；模型 ID 必须仍在当前 capabilities 目录中。

​
查询会话列表

所需权限：agent.read 按会话创建时间从新到旧返回；查询不会创建新会话，也不会触发 Agent。
next_page_token 只在还有下一页时返回，必须与原查询条件一起原样回传。

​
查询会话公开消息

所需权限：agent.read page_token 与 order 绑定。改变方向后必须从第一页重新查询；跨方向复用令牌会返回 400 invalid_page_token。
消息接口只返回已落库且适合最终用户展示的 user / assistant 文本，不返回：
  • system prompt 或 system reminder。
  • 隐藏上下文和内部消息。
  • 工具参数、工具调用和工具结果。
  • metadata、Token 用量和内部诊断信息。
该接口用于历史记录，不是实时输出通道。Run 执行期间仍应消费 SSE。

​
页面刷新恢复

推荐流程：
  1. 调用 GET /projects/{project_id}/agent/runs/current。
  2. 如果返回 submitted、working 或 input_required，用返回的 run_id 重新订阅 SSE。
  3. 如果是 input_required，使用重连后新签发的 action_id 替换本地旧 Token。
  4. 收到 message.snapshot 时整段替换本地回复文本；存在 tool_calls 时整体替换当前轮公开工具列表，缺省时保留已有工具状态。
  5. 处理重放的 run.usage 前按 usage_id 去重，再累加 credits_used；刷新前已处理的结算不能重复累计。
  6. 如果返回终态，可读取目标 conversation_id 的消息历史恢复页面。
  7. 项目从未有 Run 而返回 404 时，展示空会话状态。
runs/current 在没有活动 Run 时返回最近一次终态 Run，因此不能把 200 等同于“正在运行”。必须检查 status。 runs/current 返回最后持久化的 model 和 speed_tier，可用于恢复 UI。刚启动时它不构成与 start 响应相同的原子确认；启动响应保存本次选择，重新启动时则应按当前 capabilities 校验可选值。 公开 messages 接口仍只返回用户/助手文本，不会因为 SSE 新增 tool_calls 而返回工具参数或积分。工具展示通过对应 Run 的 SSE 快照或接入方已保存状态恢复；结算事件只可能在缓存窗口内重放，不要把历史消息当作完整积分账单。

​
SSE 断线恢复

  • 不支持 Last-Event-ID，帧 id 不能跨连接复用。
  • 重新 GET 同一 run_id 的 events 端点。
  • 保留当前文本和按 tool_call_id 维护的工具状态，等待 message.snapshot 全量校正；存在 tool_calls 时替换，缺省时保留。
  • tool.input.delta 按工具与字段追加，tool.input.snapshot 整体替换该工具输入；对重放的 run.usage 按 usage_id 去重后累计。
  • 不要重新 POST 同一 Run 来恢复 SSE；只有启动请求本身结果不确定时才使用原 Idempotency-Key 重试 start。
  • 收到 run.superseded 时保留旧 Run 的真实终态；存在 current_run_id 时结束旧订阅并切换到新 Run。

​
启动请求结果不确定

如果 POST .../agent/runs 超时：
  1. 使用相同 Idempotency-Key 和完全相同的逻辑请求重试。
  2. 不要为同一条消息生成新 Key，否则可能创建重复 Run。
  3. 如果收到 409，查询 current 并核对本地消息状态，再决定后续操作。
重试应保持相同 model、speed_tier、disable_cloud。模型和档位的解析值参与幂等摘要，省略模型但默认目录已经变化时，同一键也可能冲突；禁云 false 与省略等价，切换为 true 会改变逻辑请求。

​
数据保存建议

  • 把 project_id、conversation_id、run_id 当作不透明字符串。
  • 按 Run 保存 model、speed_tier 和本次请求的 disable_cloud，继续对话时按意图显式重传。
  • 按 Run 保存已处理的 usage_id 集合及积分累计值，至少覆盖本次运行与页面恢复；credits_used 是非负整数字符串，使用整数安全的方式累计。
  • 按 tool_call_id 区分工具状态，不使用可能重名的 file_name 作为唯一键。
  • 不把 Access Token、API Key、Action Token 或签名附件 URL 写入会话日志。
  • 历史分页游标不应长期保存或跨筛选条件复用。
  • 排障时保存接口时间、HTTP 状态、稳定错误码和 X-Meoo-Trace-Id。