Run 生命周期

本页说明如何启动、查询和取消 Agent Run，以及如何正确使用会话标识和幂等键。基础地址：https://meoo.com/open/v1

启动新会话或继续会话

POST /projects/{project_id}/agent/runs

所需权限：agent.run

查询可选模型和档位

GET /projects/{project_id}/agent/capabilities

所需权限：agent.run。返回当前可选模型、三种性能档位和默认值；模型目录可能随服务配置变化，不要硬编码。目录不可用或没有可选模型时返回 503 service_unavailable。

{
  "object": "agent_capabilities",
  "project_id": "event-signup-demo",
  "models": [
    {
      "id": "qwen3.7-plus",
      "name": "Qwen 3.7 Plus"
    }
  ],
  "speed_tiers": [
    {
      "id": "fast",
      "name": "快速"
    },
    {
      "id": "standard",
      "name": "标准"
    },
    {
      "id": "deep",
      "name": "深度"
    }
  ],
  "defaults": {
    "model": "qwen3.7-plus",
    "speed_tier": "standard"
  }
}

上述模型仅为示例，实际必须精确使用本次 models[].id 的 canonical 值；内部别名、未知或已下线的 ID 会被拒绝。fast 优先较低延迟，standard 平衡延迟、质量和消耗，deep 使用更多推理能力并可能增加延迟和消耗。

请求头

Header	必填	说明
`Authorization`	是	`Bearer <OAuth Access Token 或 meoo_ak>`
`Content-Type`	是	固定 `application/json`
`Idempotency-Key`	否	1～128 位字母、数字、`_` 或 `-`；生产环境建议必传

相同逻辑消息因网络超时而重试时，复用原 Idempotency-Key；用户发送新消息时必须生成新值。服务端在当前 24 小时内部准入窗口内识别重复请求。

请求体

字段说明

message（string，必填）：1～100000 字符，不能全为空白
conversation_id（string，可选）：不传则创建会话；传入则继续项目内已有会话
attachments（object[ ]，可选）：1～10 项，详见附件与 Skills
skills（object[ ]，可选）：0～20 项，详见附件与 Skills
model（string，可选）：capabilities 当前返回的 canonical 模型 ID；省略时使用当前 defaults.model。
speed_tier（string，可选）：fast、standard 或 deep；默认 standard。
disable_cloud（boolean，可选）：默认 false；true 仅本次 Run 禁用全部 Meoo Cloud CLI 能力，详见下文。
yolo（boolean，可选）：true 开启 YOLO 并保存状态；false 或不传不主动开启，也不能清除已持久化的 true

请求对象为严格 Schema。model、speed_tier 和 disable_cloud 是公开支持字段；内部 mode 仍不支持通过 OpenAPI 选择。不要传递内部用户 ID、MCP 配置或 Web 端扩展字段。 model 和 speed_tier 按每次启动请求独立选择，任一字段省略时使用当前 capabilities 的对应默认值；继续同一会话也不继承上次选择。希望保持配置时必须再次显式传入。服务端解析后的 model、speed_tier 会参与 Idempotency-Key 请求摘要；同一键改动任一字段，或省略模型但默认模型已经变化时，会产生幂等冲突。disable_cloud: true 也参与摘要，false 与省略等价。超时重试请复用原键及相同配置。

新会话示例

curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/runs" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: message_20260818_001" \
  --data '{
    "message": "创建一个活动报名网站，包含报名表单和报名记录看板",
    "model": "qwen3.7-plus",
    "speed_tier": "deep"
  }'

继续会话示例

curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/runs" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: message_20260818_002" \
  --data "$(jq -n --arg conversation_id "${CONVERSATION_ID}" '{
    message: "把主色调整为蓝色，并增加手机号校验",
    conversation_id: $conversation_id,
    model: "qwen3.7-plus",
    speed_tier: "standard"
  }')"

conversation_id 必须属于路径中的项目。会话不存在、属于其他项目或当前用户不可访问时返回 404。

YOLO 自动决策

需要 Agent 按服务端预置自动决策处理可自动确认的步骤时，可以发送：

{
  "message": "创建一个活动报名网站",
  "yolo": true
}

yolo 为 true 时会开启本次 Run 的 YOLO，状态会写入现有 Agent 状态快照，并供同项目后续 Run 继承。false 或不传不会主动开启，也不能清除已经持久化的 true。YOLO 仅应用预置自动决策；需要真人完成的 OAuth、Secret 或 Input 场景仍可能按现有策略取消或关闭。该字段不会改变 HTTP 响应或 SSE 事件 Schema。

单次运行禁用 Meoo Cloud

{
  "message": "构建一个不依赖 Meoo Cloud 的前端 demo",
  "disable_cloud": true
}

disable_cloud: true 禁用整个 meoo-cli cloud 命令域，包括帮助、读取、开启、绑定、数据库、鉴权、存储和云函数；项目已有云服务也不放行。不会产生云能力确认卡，yolo 不能绕过。该参数只对本次 Run 生效。同一 Run 的工具恢复、进程恢复、上下文压缩和子 Agent 保留该策略；同一 conversation 的下一次 Run 重新解析参数，不传则恢复 false。若下一轮仍需禁云，请再次传 true。外部 API 和其他能力不受限制；缺少可用后端时使用 mock 数据和模拟交互，并在交付时说明模拟部分。该参数不关闭、删除或修改已有云资源，也不是项目级开关或通用网络隔离。受限云工具调用不会因此进入 input_required，Agent 应继续完成任务。

响应

{
  "project_id": "event-signup-demo",
  "run_id": "run_01JEXAMPLE",
  "conversation_id": "conv_01JEXAMPLE",
  "status": "submitted",
  "model": "qwen3.7-plus",
  "speed_tier": "deep"
}

字段	说明
`project_id`	当前项目标识
`run_id`	本次消息对应的 Run；用于 SSE 和取消
`conversation_id`	持续会话标识；用于下一轮消息和历史查询
`status`	当前 Run 状态
`model`	本次 Run 的 canonical 模型选择值
`speed_tier`	本次 Run 的性能档位选择值

run_id 和 conversation_id 不是同一概念，必须分别保存。 start 响应报告已经校验并交给 Runtime 的本次 model 和 speed_tier 选择值；GET .../agent/runs/current 返回最后持久化的选择。Run 刚启动、首次快照尚未更新时，current 不构成与 start 相同的原子确认。新增字段向后兼容，其他 Run 操作响应仍可能省略这两项。

查询当前或最近一次 Run

GET /projects/{project_id}/agent/runs/current

所需权限：agent.read 项目存在活动 Run 时返回活动 Run；否则返回项目最近一次终态 Run。项目从未启动过 Run 时返回 404。

curl --request GET \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/runs/current" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}"

该接口适合页面刷新后的恢复，不应高频轮询替代 SSE。拿到非终态 run_id 后，重新订阅它的事件端点。如果状态为 input_required，只要阻塞工具仍有效，重连会签发新的 action_id 和 expires_at。

取消 Run

POST /projects/{project_id}/agent/runs/{run_id}/cancellations

所需权限：agent.run 请求体可以省略，也可以发送空对象 {}：

curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/runs/${RUN_ID}/cancellations" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{}'

成功后返回状态为 canceled 的 Run。Run 已经是 canceled 时幂等返回 200；completed、failed、interrupted 等其他不可取消终态返回 409 not_cancelable；generation 等并发状态变化返回 409 run_conflict。取消请求成功只代表服务端已接受并完成取消状态收口；客户端仍应停止发送新的 Action 回复，并结束该 Run 的交互 UI。

状态与终态

状态	说明
`submitted`	请求已准入
`working`	Agent 正在处理
`input_required`	Agent 等待用户输入
`completed`	正常完成
`failed`	执行失败
`canceled`	已取消
`interrupted`	执行被中断

终态为 completed、failed、canceled 和 interrupted。SSE 的 run.superseded 事件同样结束当前订阅；其 status 是旧 Run 的真实终态，并可能提供接管任务的 current_run_id。消费 SSE 时，最终 message.snapshot 和最终 run.usage（若有）均先于正常终态；正常终态是连接最后一个业务帧。主 Agent 与 Run 内图片、视频、语音、音乐可能分别结算，素材积分也可在执行过程中到达。按 usage_id 去重后累加 credits_used，不要在收到终态前主动丢弃结算事件。积分事件没有工具调用 ID，不能按事件顺序与某次工具绑定；详细规则见事件流与 Action。

常见错误

HTTP	场景	处理建议
`400`	消息、会话标识、模型、性能档位、disable_cloud 类型、附件、Skills 或幂等键格式错误	修正请求，不重试原请求体
`401`	Token/AK 无效或过期	刷新 Token 或更换有效 AK
`403`	缺少 Scope、额度不足或项目不能运行 Agent	不自动重试，提示用户处理权限或额度
`404`	项目、会话、Run 或显式 Skill 不存在/不可访问	检查标识与项目边界，不枚举资源
`409`	并发 Run、幂等请求或状态转换冲突	查询 current，再决定恢复还是新建
`429`	超过限频	遵循 `Retry-After`；SSE 重连在等待后增加抖动
`500` / `503`	Agent 服务暂时不可用	对同一消息复用原幂等键，有限重试

下一步：使用返回的 run_id 订阅事件流与 Action。

​启动新会话或继续会话

​查询可选模型和档位

​请求头

​请求体

​新会话示例

​继续会话示例

​YOLO 自动决策

​单次运行禁用 Meoo Cloud

​响应

​查询当前或最近一次 Run

​取消 Run

​状态与终态

​常见错误