附件与 Skills

Agent Run 可以携带图片、视频、普通文件和显式 Skill 选择。普通附件与 Skill 包是两条独立链路：.zip / .skill 不能作为普通附件使用，自定义 Skill 必须先通过 Skills API 上传。

附件的两种来源

文件位置	推荐方式

Run 附件 Schema

attachments 合计 1～10 项，按 kind 使用严格对象 Schema。

图片或视频

{
  "kind": "image",
  "url": "https://cdn.example.com/reference.png"
}

kind=image 或 video 时只允许 kind、url，不能携带 filename 或 type。

普通文件

{
  "kind": "file",
  "url": "https://cdn.example.com/requirements.pdf",
  "filename": "requirements.pdf",
  "type": "application/pdf"
}

字段	约束
`url`	HTTP(S) URL，最长 4096 字符
`filename`	1～255 字符，不含目录路径；不支持 `.zip` 和 `.skill`
`type`	可选的合法 MIME type，最长 255 字符

签发附件直传票据

POST /projects/{project_id}/agent/uploads

所需权限：agent.run

curl --request POST \
  --url "${MEOO_BASE_URL}/open/v1/projects/${PROJECT_ID}/agent/uploads" \
  --header "Authorization: Bearer ${ACCESS_TOKEN_OR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "filename": "requirements.pdf",
    "type": "application/pdf",
    "size": 102400
  }'

字段	必填	说明
`filename`	是	1～255 字符，不含路径，不支持 `.zip` / `.skill`
`size`	是	声明的字节数，最小 1，默认上限 50MB
`type`	否	缺省 `application/octet-stream`

允许的 type 包括 image/*、video/*、audio/*、text/*，以及 application/pdf、application/json、application/octet-stream。响应：

{
  "upload_id": "upload_01JEXAMPLE",
  "upload_url": "https://storage.example.com/signed-put",
  "file_url": "https://storage.example.com/signed-get",
  "upload_expires_at": 1785900000000,
  "file_expires_at": 1785903600000
}

使用步骤：

对 upload_url 发起一次 HTTP PUT。
Content-Type 必须与签发票据时的 type 相同；未传时用 application/octet-stream。
上传完成后，把 file_url 放入 Run 的 attachments[ ].url。
两个签名 URL 过期后重新签发，不要长期保存。

curl --request PUT \
  --upload-file ./requirements.pdf \
  --header "Content-Type: application/pdf" \
  "${UPLOAD_URL}"

upload_url 和 file_url 使用随机对象路径，但服务端不承诺签名 URL 强制 single-use。不要把地址交给无关调用方，也不要依赖它可重复使用。 size 是准入时的调用方声明值，不是存储侧强制的实际字节数；请填写真实大小。无论声明值如何，Agent 下载实际响应时仍执行 50 MiB 上限。

带附件启动 Run

{
  "message": "参考图片和需求文档创建活动报名网站",
  "attachments": [
    {
      "kind": "image",
      "url": "https://cdn.example.com/reference.png"
    },
    {
      "kind": "file",
      "url": "https://storage.example.com/signed-get",
      "filename": "requirements.pdf",
      "type": "application/pdf"
    }
  ]
}

在 Run 中选择 Skill

skills 数组每项只包含一个十进制字符串 skill_id：

{
  "message": "使用简历审阅技能分析附件",
  "skills": [
    { "skill_id": "101" }
  ]
}

最多选择 20 项，不允许重复 ID 或额外字段。服务端按调用方顺序解析，并在 Agent 启动前校验 Skill 是否存在、未删除、当前可访问且未处于禁止消费的下架状态。

`skills` 的三种语义

请求写法	语义
省略 `skills`	有 `conversation_id` 时继承该会话；新会话则继承项目最近会话的用户 Skill

| "skills": [ ] | 清除继承的用户 Skill；服务端内置 Skill 不受影响 | | 非空数组 | 用本次显式选择替换继承选择，并把结果保存到会话配置 | 显式选择的每个 Skill 都是 mandatory selection：运行时按 preload=true 处理，不允许静默过滤。选择会在 blocking/resume 以及后续省略 skills 的 Run 中继续生效。以下情况会在启动前返回通用 404：

Skill ID 不存在或已软删除。
私有 Skill 不属于当前用户。
团队 Skill 的租户、成员或套餐权限不可用。
非 owner 的市场 Skill 已下架或没有当前可消费状态。

如果多个 ID 解析为同一个运行时名称，或名称与运行时内置 Skill 冲突，请求返回 400 invalid_request。

权限边界

上传/更新私有 Skill：需要 skill.write。
在 Agent Run 中使用已可访问 Skill：只需要 agent.run。
当前不支持通过 Run 锁定 Skill 版本。
当前不支持需要 MCP OAuth 的 Skill 授权流程。

完整上传格式、32 MiB ZIP 限制、SKILL.md 规则和响应字段见 Skills API。

常见错误

HTTP	场景
`400`	附件对象、文件名、MIME、URL、Skills 数组或名称组合不合法
`403`	缺少 `agent.run`，或项目不能使用 Agent
`404`	项目不可访问，或显式选择的 Skill 不可访问/不可消费
`429`	票据签发或 Run 启动超过限频

​附件的两种来源

​Run 附件 Schema

​图片或视频

​普通文件

​签发附件直传票据

​带附件启动 Run

​在 Run 中选择 Skill

​skills 的三种语义

​权限边界

​常见错误