> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent 接入总览

Agent 接入总览 本目录按调用流程组织 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/{run_id}/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 ◀────┘ 典型接入顺序：
4. 调用 GET .../agent/capabilities 获取实时模型目录、性能档位和默认值，不要硬编码模型 ID。
5. 为用户消息生成稳定的 Idempotency-Key。
6. 调用 POST .../agent/runs，保存返回的 run\_id、conversation\_id、本次 model 和 speed\_tier；需要禁用 Meoo Cloud 时在请求中传 disable\_cloud: true。
7. 立即订阅该 run\_id 的 SSE；Write/Edit 白名单正文默认通过工具事件输出。
8. 将 message.delta 追加到回复；将 message.snapshot.content 作为全量文本替换。存在 tool\_calls 时整体替换当前轮公开工具状态，缺省时保留已有状态。
9. 收到 run.input\_required 时，根据 action.kind 和 action.input\_schema 收集输入并回复。
10. 按 usage\_id 去重并累加每条 run.usage.data.credits\_used；一条是单次结算值，同一 Run 可多次结算。最终结算事件若有，会先于正常终态。
11. 收到终态后停止重连。继续对话时把原 conversation\_id 放入新的 Run 请求；需要保持模型、档位或禁云配置时再次显式传入。 每次新 Run 的 model、speed\_tier 省略时使用当前 capabilities 默认值，disable\_cloud 省略为 false；同一 Run 的恢复和压缩保留已保存配置。禁云时不会调用 Meoo Cloud CLI 或生成云确认卡，已有云资源不会被关闭；外部 API 仍可用，缺少后端时使用 mock 并如实说明。 状态模型 Run 的已知状态包括： 状态 是否终态 客户端处理 submitted 否 已准入，准备执行 working 否 展示公开进度并继续消费 SSE input\_required 否 展示 Action；提交回复后继续订阅 completed 是 展示最终内容或预览 failed 是 展示失败并允许用户重新发起 canceled 是 展示已取消 interrupted 是 展示执行中断 遇到未知状态时按非终态处理，避免后续扩展导致客户端提前结束。 run.superseded 是结束旧订阅的事件，不是新的 Run 状态。它携带旧 Run 的真实终态，并可能提供接管任务的 current\_run\_id。 客户端需要保存什么 数据 保存期限 用途 project\_id 项目生命周期 所有项目资源路径 conversation\_id 会话生命周期 继续同一对话、读取历史 run\_id 至少保留到 Run 结束 订阅事件、取消和刷新恢复 已处理的 usage\_id 与积分累计值 至少覆盖本次 Run 和页面恢复 防止重连重放导致积分重复累计 model / speed\_tier 至少保留到 Run 结束 展示本次选择；下一次 Run 需要显式重传才能保持 请求中的 disable\_cloud 至少保留到 Run 结束 同 Run 恢复保留；下一次 Run 省略为 false 按 tool\_call\_id 维护的工具状态 Run 展示和恢复期间 处理输入 delta/snapshot 与当前轮工具快照 Idempotency-Key 至少覆盖请求重试窗口 同一消息的安全重试 action\_id 仅当前 Action，有效期内 回复问答或确认；不得解析 X-Meoo-Trace-Id 按排障需要 联系支持时定位请求 不要保存 SSE 帧 id 用于跨连接续传；服务端不支持 Last-Event-ID。断线后重新连接同一事件端点，使用 message.snapshot 恢复文本和可选的 tool\_calls，并按 usage\_id 去重结算事件。 专题文档 专题 内容 Run 生命周期 capabilities、模型与档位、单次禁云、start/current/cancel、幂等与错误 事件流与 Action 工具输入流、执行结果、文本/工具快照、积分去重、重连与 Action 附件与 Skills 公网附件、直传票据、自定义 Skill 三态选择语义 会话与恢复 参数继承、conversation 延续、历史分页、页面刷新和断线恢复 生产接入检查 ☐ 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 排查问题。