> ## 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 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 ◀────┘

典型接入顺序：

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 的已知状态包括：

| 状态 | 是否终态 | 客户端处理 |
| :- | :- | :- |
| `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 生命周期](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/bf852c42-7d2d-4ebb-b760-abe7802341dc) | capabilities、模型与档位、单次禁云、start/current/cancel、幂等与错误 |
| [事件流与 Action](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/17319bd5-e1db-4375-9a50-ea0b2415ed61) | 工具输入流、执行结果、文本/工具快照、积分去重、重连与 Action |
| [附件与 Skills](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/a051cfb9-8c14-42bf-b4c0-b6a0a00fe2af) | 公网附件、直传票据、自定义 Skill 三态选择语义 |
| [会话与恢复](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/5bdc9af8-f34f-4604-ad9c-8c90a4fae2d8) | 参数继承、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 排查问题。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.