如何先用 Files API 获取预签名上传地址再把文件引用传给 Composio 工具

如何先用 Files API 获取预签名上传地址再把文件引用传给 Composio 工具

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio

如果你的工具要读取一个文件（例如给GMAIL_SEND_EMAIL带附件、给 Google Drive 上传文件），直接把字节塞进 API 请求体会让请求体过大。Composio 的 Files API 解决的就是这个问题：先调用 upload-request 接口拿到一个预签名上传地址，把文件内容直接PUT到该地址，再把返回的文件引用传给工具的入参。Composio 把文件存在对象存储里，工具在自身侧解析文件引用，API 请求体中始终不经过原始字节。

前提是你已经有一个项目 API key，所有 Files 端点都通过x-api-key请求头携带它。生产 API 的 Base URL 是https://backend.composio.dev（见仓库中 openapi-v3.json 的 servers 定义）。端点说明见 Files 概述 和 Files API 参考。

如果 Agent 是在 session 沙箱里操作文件，文档建议优先使用 session file mount（沙箱把上传文件暴露给运行代码），配套upload_local_file、smart_file_extract等辅助方法；本文聚焦的是通过 Files API 手动完成上传再传引用的流程。

第一步：请求预签名上传地址

调用POST /api/v3/files/upload/request（v3.1 对应/api/v3.1/files/upload/request）。请求体有 5 个必填字段：

字段	说明（文档原文用途）
toolkit_slug	文件所属应用的 slug，文档示例如"gmail"、"slack"
tool_slug	文件所属动作的 slug，文档示例如"GMAIL_SEND_EMAIL"、"SLACK_UPLOAD_FILE"
filename	原始文件名，文档示例如"quarterly_report.pdf"
mimetype	原始文件的 MIME 类型，文档示例如"application/pdf"、"image/png"
md5	文件的 MD5 hash，文档说明其用于去重和完整性校验

文档在 OpenAPI 规范里给出了 Gmail 附件场景的示例请求值（toolkit_slug为gmail、tool_slug为GMAIL_SEND_EMAIL、md5为a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6），那是文档示例值；实际调用时filename、mimetype、md5要换成你自己文件的值，md5文档只说明用途、未规定计算命令。

your_composio_key替换为你的项目 API key：

curl -X POST "https://backend.composio.dev/api/v3/files/upload/request" \ -H "x-api-key: your_composio_key" \ -H "Content-Type: application/json" \ -d '{ "toolkit_slug": "gmail", "tool_slug": "GMAIL_SEND_EMAIL", "filename": "quarterly_report.pdf", "mimetype": "application/pdf", "md5": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" }'

成功时返回200，响应体包含这些字段：

• id：该 request file 的 ID；
• key：对象存储中的上传位置；
• new_presigned_url：用于上传的预签名 URL；
• metadata.storage_backend：值为s3或azure_blob_storage，决定下一步是否要加额外请求头。

注意：响应中的newPresignedUrl和type两个字段已标记为[DEPRECATED]，文档明确要求使用new_presigned_url。文档示例中new_presigned_url形如https://storage.composio.dev/projects/pr_1a2b3c4d5e6f/requests/slack/document_9mZn4q.docx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600...，实际 URL 以接口返回为准。

该接口还会检查是否已存在相同 MD5 hash 的文件来做去重，因此重复上传同一内容时行为可能命中已有对象。可能的错误响应为400、401、403、404、410，响应体均为 Error schema。

第二步：把文件字节 PUT 到预签名地址

拿到new_presigned_url后，把文件内容直接上传到这个 URL，而不是发给 Composio API：

curl -X PUT --data-binary @quarterly_report.pdf "$NEW_PRESIGNED_URL"

$NEW_PRESIGNED_URL是上一步响应中的new_presigned_url值。这一步的副作用是把本地文件内容发送到对象存储；预签名 URL 是带时效的临时地址，超期需要重新请求。

如果响应里metadata.storage_backend是azure_blob_storage，上传时要加上x-ms-blob-type: BlockBlob请求头（s3则不需要）：

curl -X PUT \ -H "x-ms-blob-type: BlockBlob" \ --data-binary @quarterly_report.pdf \ "$NEW_PRESIGNED_URL"

第三步：把文件引用传给 Composio 工具

上传完成后，工具入参里传的是文件引用而不是原始字节。文档给出的文件引用形态是{ "name", "mimetype", "s3key" }描述符，两种用法：

Python SDK 在自动文件处理关闭时，把已暂存的文件描述符直接作为工具参数传入tools.execute：

result = composio.tools.execute( "GOOGLEDRIVE_UPLOAD_FILE", user_id="user-1", arguments={"file_to_upload": prestaged_descriptor}, dangerously_skip_version_check=True, # required when running "latest" )

其中prestaged_descriptor即文档所说的{ "name", "mimetype", "s3key" }字典，文件由你自己的流水线（或上游步骤）预先暂存到 Composio 存储。

TypeScript SDK 提供了composio.files.upload(...)，它内部完成同样的暂存过程，返回的fileData直接作为工具参数传入：

import { Composio } from '@composio/core'; import path from 'path'; const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY, toolkitVersions: { googledrive: 'latest' }, }); // 暂存本地文件，得到 { name, mimetype, s3key } 描述符 const fileData = await composio.files.upload({ file: path.join(__dirname, 'document.pdf'), toolSlug: 'GOOGLEDRIVE_UPLOAD_FILE', toolkitSlug: 'googledrive' }); // 把描述符作为文件参数传给工具 await composio.tools.execute('GOOGLEDRIVE_UPLOAD_FILE', { userId: 'user-1', arguments: { file_to_upload: fileData }, dangerouslySkipVersionCheck: true, // required when running "latest" });

document.pdf是文档示例中的路径，换成你要上传的文件；user-1换成你的用户标识。文档同时说明：自动文件处理默认关闭，打开dangerouslyAllowAutoUploadDownloadFiles: true（TypeScript）或dangerously_allow_auto_upload_download_files=True（Python）后，可以直接把本地路径传给接受文件的工具，SDK 会自行上传并转换成工具期望的格式；但本地路径必须落在fileUploadDirs/file_upload_dirs配置的白名单目录内。

以上执行示例来自 Executing tools directly，其中工具执行要求配置 toolkit 版本（"latest"需配合dangerouslySkipVersionCheck）。

验证方式与可选检查

判断流程是否走通，看两处返回：

1. upload-request 返回200且包含new_presigned_url、key、metadata.storage_backend，说明预签名地址已生成；
2. 对预签名地址的PUT成功后，工具调用返回其正常执行结果（如 Google Drive 的文件详情，文档示例为result.data包含 Google Drive file details）。

另外，GET /api/v3/files/list可以列出工具生成的文件，支持toolkit_slug、tool_slug两个查询参数过滤，limit最大 50，支持 cursor 分页；响应包含items（每项含toolkit_slug、tool_slug、filename、mimetype、md5）和分页字段。这个端点文档描述为“列出工具生成的文件”，可用于核对工具侧产生的文件记录。

限制与边界

• 上传是两步流程，第二步必须直接打预签名地址，API 侧永远不接收原始字节；预签名 URL 示例中带X-Amz-Expires=3600参数，说明地址有时效，过期后需重新请求。
• newPresignedUrl与type字段已废弃，代码中不要再依赖。
• 该流程适用于“工具执行时读写文件”的场景；session 沙箱内处理文件应改用 session file mount，二者不要混在同一条链路里。

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio