如何先用 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/requestv3.1 对应/api/v3.1/files/upload/request。请求体有 5 个必填字段字段说明文档原文用途toolkit_slug文件所属应用的 slug文档示例如gmail、slacktool_slug文件所属动作的 slug文档示例如GMAIL_SEND_EMAIL、SLACK_UPLOAD_FILEfilename原始文件名文档示例如quarterly_report.pdfmimetype原始文件的 MIME 类型文档示例如application/pdf、image/pngmd5文件的 MD5 hash文档说明其用于去重和完整性校验文档在 OpenAPI 规范里给出了 Gmail 附件场景的示例请求值toolkit_slug为gmail、tool_slug为GMAIL_SEND_EMAIL、md5为a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6那是文档示例值实际调用时filename、mimetype、md5要换成你自己文件的值md5文档只说明用途、未规定计算命令。your_composio_key替换为你的项目 API keycurl -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 的 IDkey对象存储中的上传位置new_presigned_url用于上传的预签名 URLmetadata.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-AlgorithmAWS4-HMAC-SHA256X-Amz-Expires3600...实际 URL 以接口返回为准。该接口还会检查是否已存在相同 MD5 hash 的文件来做去重因此重复上传同一内容时行为可能命中已有对象。可能的错误响应为400、401、403、404、410响应体均为 Error schema。第二步把文件字节 PUT 到预签名地址拿到new_presigned_url后把文件内容直接上传到这个 URL而不是发给 Composio APIcurl -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.executeresult composio.tools.execute( GOOGLEDRIVE_UPLOAD_FILE, user_iduser-1, arguments{file_to_upload: prestaged_descriptor}, dangerously_skip_version_checkTrue, # 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: trueTypeScript或dangerously_allow_auto_upload_download_filesTruePython后可以直接把本地路径传给接受文件的工具SDK 会自行上传并转换成工具期望的格式但本地路径必须落在fileUploadDirs/file_upload_dirs配置的白名单目录内。以上执行示例来自 Executing tools directly其中工具执行要求配置 toolkit 版本latest需配合dangerouslySkipVersionCheck。验证方式与可选检查判断流程是否走通看两处返回upload-request 返回200且包含new_presigned_url、key、metadata.storage_backend说明预签名地址已生成对预签名地址的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-Expires3600参数说明地址有时效过期后需重新请求。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考