> ## 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.

# Run 生命周期

本页说明如何启动、查询和取消 Agent Run，以及如何正确使用会话标识和幂等键。

基础地址：`https://meoo.com/open/v1`

## 启动新会话或继续会话

```text theme={null}
POST /projects/{project_id}/agent/runs
```

所需权限：`agent.run`

### 查询可选模型和档位

```text theme={null}
GET /projects/{project_id}/agent/capabilities
```

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

```text theme={null}
{
  "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](https://alidocs.dingtalk.com/i/nodes/R1zknDm0WR6XzZ4LtzmdN0N7WBQEx5rG)
* `skills`（object\[ ]，可选）：0～20 项，详见 [附件与 Skills](https://alidocs.dingtalk.com/i/nodes/R1zknDm0WR6XzZ4LtzmdN0N7WBQEx5rG)
* `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` 与省略等价。超时重试请复用原键及相同配置。

### 新会话示例

```text theme={null}
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"
  }'
```

### 继续会话示例

```text theme={null}
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 按服务端预置自动决策处理可自动确认的步骤时，可以发送：

```text theme={null}
{
  "message": "创建一个活动报名网站",
  "yolo": true
}
```

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

### 单次运行禁用 Meoo Cloud

```text theme={null}
{
  "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 应继续完成任务。

### 响应

```text theme={null}
{
  "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

```text theme={null}
GET /projects/{project_id}/agent/runs/current
```

所需权限：`agent.read`

项目存在活动 Run 时返回活动 Run；否则返回项目最近一次终态 Run。项目从未启动过 Run 时返回 `404`。

```text theme={null}
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

```text theme={null}
POST /projects/{project_id}/agent/runs/{run_id}/cancellations
```

所需权限：`agent.run`

请求体可以省略，也可以发送空对象 `{}`：

```text theme={null}
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`（若有）均先于正常终态；正常终态是连接最后一个业务帧。积分可能分多次结算，按 `usage_id` 去重后累加，不要在收到终态前主动丢弃结算事件。

## 常见错误

| 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](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/17319bd5-e1db-4375-9a50-ea0b2415ed61)。