Agent OpenAPI
Agent OpenAPI 让接入方能够启动或继续 Meoo Agent、订阅实时事件、处理交互 Action，并读取公开会话历史。 基础地址：https://meoo.com/open/v1
文档导航
权限
OAuth Access Token 和用户 API Key 使用相同的业务接口，统一放在 Bearer Header 中：
核心对象
所有标识都应按不透明字符串保存和原样传递，不要解析其格式。
接口一览
最小调用流程
启动前调用GET /projects/{project_id}/agent/capabilities（agent.run）获取实时模型目录、性能档位及默认值。model 必须精确使用 models[].id，内部别名和下线 ID 会返回 400 invalid_request；模型目录不可用返回 503 service_unavailable。以下模型 ID 仅作示例，实际以接口返回为准。
speed_tier 支持 fast（低延迟优先）、standard（均衡默认）、deep（更多推理能力，可能增加延迟和消耗）。内部 mode 仍不支持通过 OpenAPI 选择。
启动 Run：
yolo: true：
yolo 为 true 时会开启本次 Run 的 YOLO，状态会写入现有 Agent 状态快照，并供同项目后续 Run 继承。false 或不传不会主动开启，也不能清除已经持久化的 true。YOLO 仅应用预置自动决策；需要真人完成的 OAuth、Secret 或 Input 场景仍可能按现有策略取消或关闭。该字段不会改变 HTTP 响应或 SSE 事件 Schema。
单次运行禁用 Meoo Cloud
启动时可传disable_cloud: true，默认 false，仅本次 Run 生效。它禁用全部 meoo-cli cloud 能力（包括帮助、读取、开启、绑定、数据库、鉴权、存储和云函数），已有云服务也适用；不会产生云能力确认卡，YOLO 不能绕过。
false。此参数不关闭或删除已有云资源，不限制外部 API；缺少可用后端时使用 mock 数据和模拟交互，并在交付时说明模拟部分。
响应会包含后续需要保存的三个标识：
model、speed_tier 是已校验并交给 Runtime 的本次选择；runs/current 返回最后持久化值，刚启动时不构成与 start 相同的原子确认。两字段每次启动独立选择：省略使用 capabilities 当前默认值，继续会话也不继承上次选择；需要保持配置时再次显式传入。解析后的选择参与幂等摘要，重试应保持相同配置。disable_cloud 的 true 也参与摘要，false 与省略等价。
订阅事件：
agent.read，默认包含 tool.input.delta、tool.input.snapshot。Write 公开 content；Edit 公开 old_string、new_string 及最终 replace_all。delta 按 tool_call_id 和字段追加，snapshot 整体替换该工具公开输入。complete: true 仅代表参数生成完成；truncated: true 表示公开内容受限，内部仍按完整参数执行。
Read 的 tool.call 可带安全 basename file_name；Skill 可带 skill.skill_name 和可选 display_name。tool.call.status: completed 仅表示调用结束，实际结果看 outcome（succeeded、failed、canceled）。不公开目录路径、Read 正文、Skill 原始参数或原始工具结果。
持久化 message.snapshot 的可选 tool_calls 恢复当前轮 Read/Write/Edit/Skill 状态：存在时整体替换工具列表，缺省时保留已有工具列表；content 继续采用全文替换。
run.usage 包含稳定的 usage_id 与非负整数字符串 credits_used。每条是单次结算值，一个 Run 可有多条；重连可能重放，必须按 usage_id 去重后累加。最终文本/工具快照及最终结算事件（若有）在正常终态前发送，终态是最后一个业务帧。结算不可用时不会伪造事件；未收到不代表零消耗。
收到 run.completed、run.failed、run.canceled、run.interrupted 或 run.superseded 后结束本次 Run 的展示。收到 run.input_required 时，按事件中的 action.input_schema 收集用户输入并调用 Action 回复接口。收到 preview.ready 时，使用事件中的短时 opaque url 打开预览。
预览链接与公开壳
POST/projects/{project_id}/agent/preview-links 是需要 OAuth Access Token 或用户 API Key 的受保护 JSON API，使用 agent.read。请求体省略或传 {}；调用方不能指定 Sandbox、目标 URL、端口或 TTL。本接口不读取也不使用 Idempotency-Key。就绪时返回短时 opaque URL 和 Unix 毫秒 expires_at：
202、Retry-After: 5 和 retry_after_ms: 5000。按响应等待后重试同一 POST；不要创建新的 Agent Run 代替重试。链接过期后也调用这个受保护接口重新签发。
失败响应保持不枚举资源和不泄露上游细节：项目不存在或不可见返回 404 not_found；当前项目形态不可预览返回 409 preview_not_ready；签名配置错误、依赖或上游暂不可用返回 503 service_unavailable。
返回 URL 指向 GET /open/preview/{preview_ticket}。这是无需 Authorization 的公开 HTML 浏览器导航路由，只验证 URL 自带的短时 Ticket，并返回带独立 CSP 的全屏 iframe 壳。第三方前端只应把整个 opaque URL 设为 iframe src；不要解析、拼接子路径、写入公开日志或长期存储。公开壳不会恢复 Sandbox，失效后由第三方后端重新签发。
Agent SSE 仅在内部 dev server 已经是 running 且短时链接签发成功时发送 preview.ready；starting 或失败不会产生该事件，也不会暴露 raw Sandbox URL。事件链接过期后，同样调用上述受保护 POST 重新签发。
稳定交互语义
runs/current返回input_required时，使用该run_id重新订阅 events；只要阻塞工具仍有效，建连或重连会签发新的action_id和expires_at。- Action Token 过期返回
409 action_expired，已回复返回409 action_already_responded，Run generation 已变化返回409 run_conflict。 - Run 已经是
canceled时，重复取消会幂等返回200；其他不可取消终态返回409 not_cancelable。 - Agent SSE 当前使用 60 秒固定限频窗口。
Retry-After: 60是固定窗口的安全等待上界，不是剩余 TTL；等待后增加少量随机抖动再重连。 run.working只表示 Run 正在处理；公开阶段和进度文案由tool.call的phase与message承载。run.superseded.data.status是旧 Run 的真实终态；current_run_id仅标识接管的新 Run。