上传文件并作为调用输入

Invoke API 不接受 Base64 文件内容。先通过上传接口得到限时 URL，再把 URL 放入 Invoke 请求的 files 数组。

上传文件

使用与 Invoke API 相同的 dbg_ 或 agt_ Token：

curl -X POST "{base_url}/api/agents/Upload" \
  -H "Authorization: Bearer {agent_token}" \
  -F "file=@./contract.pdf"

一次请求可以重复 file 表单字段。下面的请求上传两个文件：

curl -X POST "{base_url}/api/agents/Upload" \
  -H "Authorization: Bearer {agent_token}" \
  -F "file=@./contract.pdf" \
  -F "file=@./appendix.png"

响应中的每个记录包含 id、filename、mime、url 和 expire_at。

在调用中引用 URL

curl -X POST "{base_url}/api/agents/Invoke" \
  -H "Authorization: Bearer {agent_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "总结合同中的终止条款",
    "files": [
      "https://example.com/api/media/md_xxxxxxxxxxxxxxxx"
    ],
    "stream": false
  }'

模型或工具是否能理解具体 MIME 类型，取决于智能体实例的模型和能力配置。上传成功只表示文件已转存并可通过 URL 访问。

遵守文件限制

文件数量、单文件大小、文件 URL 有效期和 MIME 类型由部署配置决定。生产接入前，请向部署管理员确认目标环境的限制，并让调用方处理超限、类型不支持和 URL 过期错误。

保护上传内容

• URL 在有效期内可以被下游模型或工具读取。
• 不在日志中记录完整限时 URL。
• 不把上传接口当作长期文件存储。
• 文件过期后重新上传，不要缓存失效 URL。
• 对敏感文件确认模型服务和外部工具的数据处理边界。

处理上传错误

检查错误信封中的 data.reason 和消息。常见原因包括：

• 缺少 file 表单字段。
• 文件数量超过上限。
• 文件超过部署允许大小。
• MIME 类型不在允许列表中。
• 存储服务未配置或暂时不可用。