Agent Run 可以携带图片、视频、普通文件、ZIP 素材附件和显式 Skill 选择。普通文件使用 URL 附件;ZIP 使用独立的上传、确认及
Meoo 会拒绝本地、私网和链路本地地址。普通 URL 附件必须能被服务端访问,实际下载响应执行 50 MiB 上限。ZIP 的压缩包上传限额按账号权益及返回的
只允许
所需权限:
允许的
使用步骤:
ZIP 使用独立的
调用示例(请将
响应示例:
请求体为 ZIP 原始字节,
请求体可以省略,或发送空对象
服务端校验上传归属与存储中的实际文件大小。重复确认返回同一批次,不会重新创建或重置处理任务。响应:
将确认响应中的
以上
假设当前目录已有一个普通素材压缩包
步骤 1:读取真实文件大小,申请 ZIP 上传票据
使用文件的实际字节数生成请求,避免手填
成功响应包含
PUT 完成前不要确认上传。
成功响应示例:
步骤 4:把确认响应中的 attachment 放进 Run 请求
直接使用确认接口返回的
同一条消息重试时复用本次
确认上传成功表示原始 ZIP 已落到存储;解包、内容审核、素材入库和同步到沙箱在 Run 启动后执行。通过 Archive 工具事件及最终回复判断处理结果,不能仅用
最多选择 20 项,不允许重复 ID 或额外字段。服务端按调用方顺序解析,并在 Agent 启动前校验 Skill 是否存在、未删除、当前可访问且未处于禁止消费的下架状态。
显式选择的每个 Skill 都是 mandatory selection:运行时按
kind: archive 引用流程;自定义 Skill 包(.zip / .skill)必须先通过 Skills API 上传。
附件来源与上传方式
| 文件位置 | 推荐方式 |
|---|---|
| 普通文件已有公网 HTTP(S) URL | 直接放入 attachments[ ].url |
| 普通文件仅存在于本地设备或私有服务 | 先通过 agent/uploads 签发票据并上传,再使用返回的 file_url |
| ZIP 素材附件 | 通过 agent/archives 申请票据,PUT 上传并 confirm 后使用 archive_id |
max_size_bytes 判断,见下方「ZIP 附件上传与处理」。
Run 附件 Schema
attachments 合计 1~10 项,按 kind 使用严格对象 Schema。
图片或视频
kind=image 或 video 时只允许 kind、url,不能携带 filename 或 type。
普通文件
| 字段 | 约束 |
|---|---|
url | HTTP(S) URL,最长 4096 字符 |
filename | 1~255 字符,不含目录路径;不支持 .zip 和 .skill |
type | 可选的合法 MIME type,最长 255 字符 |
ZIP 素材附件
kind、archive_id;不能携带 url、filename 或 type。archive_id 使用确认上传接口返回的字符串,每次 Run 最多一个 ZIP。
签发普通附件直传票据
agent.run
| 字段 | 必填 | 说明 |
|---|---|---|
filename | 是 | 1~255 字符,不含路径,不支持 .zip / .skill |
size | 是 | 声明的字节数,最小 1,默认上限 50MB |
type | 否 | 缺省 application/octet-stream |
type 包括 image/*、video/*、audio/*、text/*,以及 application/pdf、application/json、application/octet-stream。
响应:
- 步骤 1:对
upload_url发起一次 HTTPPUT。 - 步骤 2:
Content-Type必须与签发票据时的type相同;未传时用application/octet-stream。 - 步骤 3:上传完成后,把
file_url放入 Run 的attachments[ ].url。 - 步骤 4:两个签名 URL 过期后重新签发,不要长期保存。
upload_url 和 file_url 使用随机对象路径,但服务端不承诺签名 URL 强制 single-use。不要把地址交给无关调用方,也不要依赖它可重复使用。
size 是准入时的调用方声明值,不是存储侧强制的实际字节数;请填写真实大小。无论声明值如何,Agent 下载实际响应时仍执行 50 MiB 上限。
带附件启动 Run
ZIP 附件上传与处理
ZIP 使用独立的 archives 上传与确认流程;agent/uploads 和 kind: file 不接受 ZIP。以下接口均以 /open/v1 为前缀,签发票据、确认上传和启动 Run 都需要 agent.run。
1. 申请 ZIP 上传票据
filename 为不含目录路径的 ZIP 文件名;size 为文件的真实字节数(正整数)。例如:
size 替换为实际字节数):
archive_id 必须作为字符串保存。upload_expires_at 为 Unix 毫秒时间戳;URL 过期后应重新申请票据。单个 ZIP 的压缩包大小受账号上传权益限制,以本次响应的 max_size_bytes 为准:权益允许时支持 500 MiB,缺省为 50 MiB,不应为所有账号硬编码 500 MiB。
2. 向签名地址 PUT 上传
Content-Type 必须为 application/zip。直接使用返回的 upload_url;向存储签名地址上传时,不要附带 Meoo 的 Bearer Token 或 API Key。签名 URL 不保证强制单次使用,上传后不要再覆盖原对象,也不要公开或写入日志。
3. 确认 ZIP 已上传
{}:
4. 携带返回的 attachment 启动 Run
将确认响应中的 attachment 原样放入 attachments:
archive_id 为示例,实际使用确认响应中的值。网络重试同一消息时复用原幂等键;发送新消息时使用新值。
完整示例:本地 materials.zip 上传后用于 Run
假设当前目录已有一个普通素材压缩包 materials.zip,其中包含需要 Agent 读取的文档、图片等文件。下面使用新增的 agent/archives 接口完成:申请票据 → PUT 上传 ZIP → 确认上传 → 携带返回的附件启动 Run,共四次 HTTP 请求。
以下命令在同一个 Bash / zsh 终端中按顺序执行,需要 curl 和 Python 3。每一步成功后再执行下一步。所有 OpenAPI 请求使用同一调用方和同一个项目;凭证需要 agent.run 权限,订阅事件另需 agent.read。PROJECT_ID 填写项目的 url_id。
size 与本地文件不一致。
archive_id、upload_url、upload_expires_at 和 max_size_bytes。上传上限以本次响应为准;账号权益允许时可达 500 MiB。文件超过上限时,申请票据会返回 413 artifact_too_large。
步骤 2:向 upload_url PUT 上传原始 ZIP
从响应自动提取地址和字符串 ID,再上传文件本身。签名上传地址已包含鉴权信息,PUT 请求只设置 Content-Type: application/zip。
upload_url 过期后需要重新申请票据并上传。
步骤 3:确认上传,取得可用于 Run 的 attachment
attachment,无需手动复制 ID。下面生成的请求形如 {"message":"…","attachments":[{"kind":"archive","archive_id":"123456789"}]}。
IDEMPOTENCY_KEY,不要重新生成;新消息再生成新值。每次 Run 最多携带一个 ZIP。
查看处理进度和最终回复
Run 启动成功后,用响应中的 run_id 订阅 SSE:
run.completed 判断 ZIP 成功。事件处理方式见事件流与 Action。
限制与处理结果
- 每次 Run 最多一个 ZIP,可以与图片、视频和普通文件混用;
attachments合计不超过 10 项。 - 引用仅对当前上传用户、项目和客户端有效;未确认、跨用户、跨项目或跨客户端的 ZIP 引用不能用于启动 Run。
- 外部 ZIP URL 不能直接作为 Run 附件使用,应先取得 ZIP 文件,再通过本节流程上传。
- 确认成功仅表示原始 ZIP 已上传,不代表已经解包或可供 Agent 使用。Run 启动后,由 Archive 流程进行解包、内容审核、素材入库及同步到沙箱。
- 使用现有 SSE 查看工具进度和回复;
run.completed表示本轮运行结束,不能单独作为 ZIP 处理成功的依据,需结合 Archive 工具的outcome和最终回复判断。详见事件流与 Action。 - 取消 Run 沿用现有 ZIP 取消处理。素材已经入库后的沙箱同步失败,不表示素材已回滚;按 Agent 返回的原因处理,需要重试时明确要求重试该 ZIP。
- 这是 ZIP 素材附件能力,不会将 ZIP 导入为项目源码。源码导入使用源码导入 API(
POST /projects/import);自定义 Skill 包继续使用 Skills API。
ZIP 上传常见错误
| HTTP / code | 场景与处理 |
|---|---|
409 invalid_request | ZIP 尚未上传完成;完成 PUT 后再确认 |
413 artifact_too_large | 声明或实际大小超过账号限额;检查 max_size_bytes 并缩小文件 |
404 not_found | 上传、项目或引用不属于当前调用方;检查用户、项目与客户端 |
503 service_unavailable | 上传权益或依赖服务暂不可用;根据错误详情处理 |
400 invalid_request | 文件名、字节数或附件 Schema 不合法;修正参数 |
在 Run 中选择 Skill
skills 数组每项只包含一个十进制字符串 skill_id:
skills 的三种语义
| 请求写法 | 语义 |
|---|---|
省略 skills | 有 conversation_id 时继承该会话;新会话则继承项目最近会话的用户 Skill |
"skills": [ ] | 清除继承的用户 Skill;服务端内置 Skill 不受影响 |
| 非空数组 | 用本次显式选择替换继承选择,并把结果保存到会话配置 |
preload=true 处理,不允许静默过滤。选择会在 blocking/resume 以及后续省略 skills 的 Run 中继续生效。
以下情况会在启动前返回通用 404:
- Skill ID 不存在或已软删除。
- 私有 Skill 不属于当前用户。
- 团队 Skill 的租户、成员或套餐权限不可用。
- 非 owner 的市场 Skill 已下架或没有当前可消费状态。
400 invalid_request。
权限边界
- 上传/更新私有 Skill:需要
skill.write。 - 在 Agent Run 中使用已可访问 Skill:只需要
agent.run。 - 当前不支持通过 Run 锁定 Skill 版本。
- 当前不支持需要 MCP OAuth 的 Skill 授权流程。
SKILL.md 规则和响应字段见 Skills API。
常见错误
| HTTP | 场景 |
|---|---|
400 | 附件对象、文件名、MIME、URL、Skills 数组或名称组合不合法 |
403 | 缺少 agent.run,或项目不能使用 Agent |
404 | 项目不可访问,或显式选择的 Skill 不可访问/不可消费 |
429 | 票据签发或 Run 启动超过限频 |

