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

# AI 生成 API

# Agent OpenAPI

Agent OpenAPI 让接入方能够启动或继续 Meoo Agent、订阅实时事件、处理交互 Action，并读取公开会话历史。

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

## 文档导航

| 目标                 | 文档                                                                                                               |
| :----------------- | :--------------------------------------------------------------------------------------------------------------- |
| 从项目到完成一次 Agent Run | [Agent 接入总览](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/902f9879-a028-41dc-829e-6ad2525780a3)  |
| 启动、查询和取消 Run       | [Run 生命周期](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/bf852c42-7d2d-4ebb-b760-abe7802341dc)    |
| 消费 SSE、回复问答或确认     | [事件流与 Action](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/17319bd5-e1db-4375-9a50-ea0b2415ed61) |
| 使用文件、图片和自定义 Skill  | [附件与 Skills](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/a051cfb9-8c14-42bf-b4c0-b6a0a00fe2af)  |
| 继续会话、读取消息和断线恢复     | [会话与恢复](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/5bdc9af8-f34f-4604-ad9c-8c90a4fae2d8)       |
| 上传私有 Skill ZIP     | [Skills API](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/7b25c37b-1a42-40e8-8ae8-6196a592c345)  |

## 权限

| Scope         | 能力                                           |
| :------------ | :------------------------------------------- |
| `agent.run`   | 查询模型与性能档位、启动或取消 Run、签发附件上传票据、回复 Action       |
| `agent.read`  | 查询当前 Run、订阅默认包含 Write/Edit 正文的 SSE、读取会话和公开消息 |
| `skill.write` | 上传或更新私有 Skill；运行已上传 Skill 不需要该 Scope         |

OAuth Access Token 和用户 API Key 使用相同的业务接口，统一放在 Bearer Header 中：

```text theme={null}
Authorization: Bearer <access_token_or_meoo_ak>
```

## 核心对象

| 对象           | 说明                                             |
| :----------- | :--------------------------------------------- |
| Project      | Agent 操作所在的项目；路径中的 `project_id` 使用项目 `url_id`  |
| Conversation | 用户与 Agent 的持续会话；后续 Run 可传 `conversation_id` 继续 |
| Run          | Agent 对一条用户消息的处理任务；由 `run_id` 标识               |
| Event Stream | 指定 Run 的 SSE 实时事件流                             |
| Action       | Agent 暂停并等待用户问答或确认时返回的短期交互凭据                   |

所有标识都应按不透明字符串保存和原样传递，不要解析其格式。

## 接口一览

| 方法     | 路径                                                                      | Scope        | 用途                |
| :----- | :---------------------------------------------------------------------- | :----------- | :---------------- |
| `GET`  | `/projects/{project_id}/agent/capabilities`                             | `agent.run`  | 查询当前可选模型、性能档位和默认值 |
| `POST` | `/projects/{project_id}/agent/runs`                                     | `agent.run`  | 启动新会话或继续已有会话      |
| `GET`  | `/projects/{project_id}/agent/runs/current`                             | `agent.read` | 查询项目当前或最近一次 Run   |
| `GET`  | `/projects/{project_id}/agent/runs/{run_id}/events`                     | `agent.read` | 订阅指定 Run 的 SSE    |
| `POST` | `/projects/{project_id}/agent/runs/{run_id}/cancellations`              | `agent.run`  | 取消 Run            |
| `POST` | `/projects/{project_id}/agent/action-responses`                         | `agent.run`  | 回复当前可交互 Action    |
| `POST` | `/projects/{project_id}/agent/uploads`                                  | `agent.run`  | 签发附件直传票据          |
| `POST` | `/projects/{project_id}/agent/preview-links`                            | `agent.read` | 获取或重新签发短时预览壳 URL  |
| `GET`  | `/projects/{project_id}/agent/conversations`                            | `agent.read` | 分页查询会话            |
| `GET`  | `/projects/{project_id}/agent/conversations/{conversation_id}/messages` | `agent.read` | 分页查询公开消息          |

## 最小调用流程

启动前调用 `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：

```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"}'
```

需要 Agent 按服务端预置自动决策处理可自动确认的步骤时，在请求中传 `yolo: true`：

```text theme={null}
{
  "message": "创建一个活动报名网站",
  "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 不能绕过。

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

同一 Run 的工具恢复、进程恢复、上下文压缩及子 Agent 保留禁云策略；下一次 Run（包括同会话继续）不传则恢复 `false`。此参数不关闭或删除已有云资源，不限制外部 API；缺少可用后端时使用 mock 数据和模拟交互，并在交付时说明模拟部分。

响应会包含后续需要保存的三个标识：

```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"
}
```

启动响应的 `model`、`speed_tier` 是已校验并交给 Runtime 的本次选择；`runs/current` 返回最后持久化值，刚启动时不构成与 start 相同的原子确认。两字段每次启动独立选择：省略使用 capabilities 当前默认值，继续会话也不继承上次选择；需要保持配置时再次显式传入。解析后的选择参与幂等摘要，重试应保持相同配置。`disable_cloud` 的 `true` 也参与摘要，`false` 与省略等价。

订阅事件：

```text theme={null}
curl --no-buffer \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/runs/${RUN_ID}/events" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Accept: text/event-stream"
```

SSE 只需 `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`：

```text theme={null}
{
  "object": "preview_link",
  "project_id": "event-signup-demo",
  "status": "ready",
  "url": "https://meoo.com/open/preview/opaque-preview-ticket",
  "expires_at": 1787652600000
}
```

Sandbox 恢复或 dev server 启动仍在后台进行时返回 `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。

## 共同约定

* 启动 Run 的 `Idempotency-Key` 可选，但生产环境强烈建议每条用户消息都生成；相同逻辑消息重试时复用，不同消息必须更换。
* 相同 `Idempotency-Key` 的内部准入去重窗口为 24 小时。
* 同一项目的资源仍受项目权限、账号状态和额度约束；Scope 不会绕过业务权限。
* 无权访问的项目、会话、Run 或 Skill 通常与资源不存在一样返回 `404`。
* 请求对象是严格 Schema；未声明字段会返回 `400 invalid_request`。
* 调用方必须忽略未知响应字段、未知事件名和未知枚举值。
* 详细的错误、限频、缓存和 SSE 规则见 [通用协议](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/de50f6a7-356b-405b-9dbe-374db0e46b3e) 与 [运行与安全](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/e2b9545e-e018-428a-adeb-b4c9cdf7222c)。