Skip to main content
本目录按调用流程组织 Agent OpenAPI 文档，重点说明客户端应如何组合接口、维护状态和处理恢复。

​
开始前

你需要：
  1. OAuth Access Token 或用户 API Key。
  2. 一个可访问项目的 url_id，作为 Agent 路径中的 project_id。
  3. 查询模型与性能档位、启动和交互使用 agent.run；读取状态、SSE（默认包含 Write/Edit 正文）和历史使用 agent.read。 项目不存在时，可以先通过 POST /open/v1/projects 创建，详见 用户与项目 API。
生命周期 GET agent/capabilities ── 选择 model + speed_tier │ POST agent/runs（可选 disable_cloud） │ ├─ 保存 run_id + conversation_id + 本次选择 │ └─ GET agent/runs//events ├─ run.working / tool.call / tool.input.* / message.* / preview.ready ├─ run.input_required ── POST agent/action-responses ──┐ ├─ run.usage（可多次，按 usage_id 去重累加） │ └─ 最终 snapshot / usage（若有）→ terminal event ◀────┘ 典型接入顺序：
  1. 调用 GET …/agent/capabilities 获取实时模型目录、性能档位和默认值，不要硬编码模型 ID。
  2. 为用户消息生成稳定的 Idempotency-Key。
  3. 调用 POST …/agent/runs，保存返回的 run_id、conversation_id、本次 model 和 speed_tier；需要禁用 Meoo Cloud 时在请求中传 disable_cloud: true。
  4. 立即订阅该 run_id 的 SSE；Write/Edit 白名单正文默认通过工具事件输出。
  5. 将 message.delta 追加到回复；将 message.snapshot.content 作为全量文本替换。存在 tool_calls 时整体替换当前轮公开工具状态，缺省时保留已有状态。
  6. 收到 run.input_required 时，根据 action.kind 和 action.input_schema 收集输入并回复。
  7. 按 usage_id 去重并累加每条 run.usage.data.credits_used；一条是单次结算值，同一 Run 可多次结算。最终结算事件若有，会先于正常终态。
  8. 收到终态后停止重连。继续对话时把原 conversation_id 放入新的 Run 请求；需要保持模型、档位或禁云配置时再次显式传入。
  9. 每次新 Run 的 model、speed_tier 省略时使用当前 capabilities 默认值，disable_cloud 省略为 false；同一 Run 的恢复和压缩保留已保存配置。禁云时不会调用 Meoo Cloud CLI 或生成云确认卡，已有云资源不会被关闭；外部 API 仍可用，缺少后端时使用 mock 并如实说明。

​
状态模型

Run 的已知状态包括： 遇到未知状态时按非终态处理，避免后续扩展导致客户端提前结束。 run.superseded 是结束旧订阅的事件，不是新的 Run 状态。它携带旧 Run 的真实终态，并可能提供接管任务的 current_run_id。

​
客户端需要保存什么

不要保存 SSE 帧 id 用于跨连接续传；服务端不支持 Last-Event-ID。断线后重新连接同一事件端点，使用 message.snapshot 恢复文本和可选的 tool_calls，并按 usage_id 去重结算事件。

​
专题文档

​
生产接入检查

☐ Token 和 API Key 只保存在可信服务端。 ☐ 每条用户消息使用独立 Idempotency-Key，超时重试复用原键及相同配置。 ☐ run_id 与 conversation_id 分开保存，没有混用。 ☐ 模型选项来自 capabilities；模型和档位省略时使用本次默认值，继续会话时按需显式重传。 ☐ disable_cloud 仅本次 Run 生效；同 Run 恢复保留，下一次 Run 省略为 false，YOLO 不能绕过。 ☐ SSE 使用 Authorization Header，没有把 Token 放进 Query。 ☐ 凭证具有 agent.read，并按 tool_call_id 和字段正确处理默认发送的工具 delta/snapshot。 ☐ message.snapshot.content 使用替换语义；tool_calls 存在时整体替换，缺省时保留已有工具状态。 ☐ 区分参数生成完成与工具执行成功，实际结果读取 tool.call.outcome，并处理 truncated 标记。 ☐ run.usage 按 usage_id 去重，使用整数安全的方式累加字符串 credits_used；缺失事件不视为零消耗。 ☐ 能处理 run.input_required 的 answers 和 confirmation 两种 Action。 ☐ 能识别 unsupported_action 并引导用户到 Meoo Web。 ☐ 重连 input_required Run 时，用最新签发的 Action Token 替换旧 Token。 ☐ 将正常终态作为最后一个业务帧处理；终态后停止重连，未知事件和字段能够被忽略。 ☐ 附件签名 URL 和 Action Token 没有进入日志。 ☐ 支持人员可以用 X-Meoo-Trace-Id 排查问题。