Composio Tool Router 文件传递指南：session 文件路径与 FileUploadable s3key 的正确用法

Composio Tool Router 文件传递指南session 文件路径与 FileUploadable s3key 的正确用法【免费下载链接】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本文聚焦 Composio Tool Router 场景下的一个高频踩坑点session 文件如/workspace/output/...、/mnt/files/...与 toolkit 的FileUploadable输入是两种不同的抽象不能把路径直接塞进s3key。读完本文你将掌握 workbench/meta tools 场景下get_mount_file_s3_key与upload_local_file的正确调用方式、SDK/API 流程中先上传再传新文件对象的标准姿势以及Failed to download file with s3key ... storage returned HTTP 404这类错误的定位与恢复方法。背景Tool Router 会话与文件存储的关系Tool Router 会话trs_*是一个长期存在的记录它圈定用户、toolkit 与工具访问范围、认证与账号选择以及会话运行时资源——包括 sandbox 文件参见 Tool Router 会话指南。在会话执行过程中文件可能出现在多个位置/workspace/output/...部分工作流生成的输出目录/mnt/files/远程 sandbox 的持久化文件挂载点。代码在 sandbox 内读写该目录且挂载在 sandbox 重启后依然保留——例如切换计算档位会重建 sandbox、清空内存态但/mnt/files/不丢见 Remote sandbox 文档本地机器路径/home/user/report.csv这类运行 agent 的机器上的路径Composio 托管的 staging 存储通过上传接口得到的一批file_...句柄 / S3 key。而 toolkit 动作的FileUploadable输入期望的是一个已由 Composio 托管的文件对象即{ name, mimetype, s3key }三元组。Tool Router 在执行 toolkit 动作前会先用s3key解析resolve出真实文件内容再交给 provider 的 API。这两套体系互不通用。核心结论session 路径不是 FileUploadable 的存储键原文档 mcp-tool-router-files.md 给出的首要原则是Tool Router session 文件与 toolkitFileUploadable输入是不同的抽象。不要直接把/workspace/output/...、/mnt/files/...、本地机器路径或旧的/外来的file_...句柄当作s3key传入。换句话说s3key不是任意文件路径而是 Composio 内部存储staging 存储里某个已上传对象的键。把 sandbox 内路径或本地路径直接当作s3keyTool Router 在执行时根本无法定位文件内容最终会在解析阶段失败详见下文错误排查小节。这一点也能从底层实现得到印证在 Python SDK 中FileUploadable是一个显式的模型类字段就是name、mimetype、s3key三者并且带json_schema_extra{file_uploadable: True}标记让后端 schema 识别该参数属于文件上传类型见 python/composio/core/models/_files.py#L522-L527TypeScript 侧同样定义了s3key: string结构见 ts/packages/core/src/types/files.types.ts。s3key的语义是已 staging 的存储对象键而非文件系统路径。场景一workbench / meta tools 可用时的正确做法当 workbench / meta tools 可用即会话启用了远程 sandbox、COMPOSIO_REMOTE_WORKBENCH等 meta tools参见 How Composio Works 中的 meta tools 说明时按文件所处位置分两种情况处理1. 文件已在/mnt/files挂载目录下使用get_mount_file_s3_key(file.ext)获取该文件的托管键。由于/mnt/files/是持久挂载sandbox 内代码写入的结果天然就在挂载点上直接用这个 helper 把它转成可传给 toolkit 动作的存储键。2. 文件在 sandbox 的其他路径使用upload_local_file(/path/to/file.ext)先把它上传到 Composio 云存储。upload_local_file是每个 sandbox 预初始化的内置 helper 之一作用是把生成的文件报告、CSV、图片等上传到云存储并返回下载 URL / 存储键见 Remote sandbox 内置 helpers 表格本地 sandbox 场景也有同名 helper见 Local sandbox 文档。3. 把返回的键传给 toolkit 动作无论用上面哪种方式最终都以标准FileUploadable描述子传入{ name: file.ext, mimetype: text/csv, s3key: 返回的 key }name是给 provider 的文件名mimetype是 MIME 类型s3key必须是刚刚由上面 helper 返回的、新鲜的存储键。注意不要把旧的或其它会话产生的s3key拿来复用。场景二SDK / API 流程中的正确做法在 SDK / API 流程中没有 workbench 环境帮你做路径 → 托管对象的转换因此原则是先上传或 staging文件再把新返回的文件对象传给动作。以 Python SDK 为例FileUploadable提供了两条类方法工厂见 python/composio/core/models/_files.py#L529-L668FileUploadable.from_url(client, url, tool, toolkit)从公开 URL 拉取内容后上传到 S3返回带s3key的对象FileUploadable.from_path(client, file, tool, toolkit, ...)从本地路径上传。该方法内部先做安全校验敏感文件保护、上传目录 allowlist 等再通过预签名上传先_request_presigned_upload拿到预签名 URL再upload上传内容得到存储键。调用链大致是uploadable FileUploadable.from_path( clientcomposio.http_client, file/home/user/report.csv, toolGMAIL_SEND_EMAIL, # 动作所属工具 toolkitGMAIL, # 动作所属 toolkit ) # 之后把 uploadable 作为该动作的 FileUploadable 参数传入TypeScript 侧也遵循同一模型上传工具会先把文件推到 S3得到s3key后组装{ name, mimetype, s3key }描述子见 ts/packages/core/src/utils/fileUtils.node.ts#L319-L333FileToolModifier在执行前会把参数树中的文件叶子统一替换为{ name, mimetype, s3key }形式见 ts/packages/core/src/utils/modifiers/FileToolModifier.node.ts#L53。需要特别注意的是每次执行动作前都应重新上传/重新 staging拿到新鲜的s3key。旧 key 可能已被清理、过期或从未属于当前会话直接复用极易触发解析失败。错误排查Failed to download file with s3key ... storage returned HTTP 404当动作报出Failed to download file with s3key ... storage returned HTTP 404请先明确错误发生的位置这个错误发生在Tool Router / SDK 解析 Composio 托管的 staging 文件阶段也就是provider 收到文件之前它不代表 provider 侧有任何问题也不代表你的文件内容错误——而是s3key无法在 Composio 存储中解析到对应对象。常见根因恰好就是本文开头列举的几种误用把/workspace/output/...、/mnt/files/...或本地机器路径直接当作s3key复用了旧的、其它会话的或外来的file_...句柄上传后存储对象已被清理或过期。修复步骤重新 staging 文件回到上面的场景一或场景二流程拿到新返回的文件对象后用它的s3key重试。只要走通先托管、再传键的路径这个 404 就会消失。小结记住这条决策链文件位置处理方式传给动作的值/mnt/files/挂载内get_mount_file_s3_key(file.ext)返回的新 keysandbox 其它路径upload_local_file(/path/to/file.ext)返回的新 key本地机器路径SDK/APIFileUploadable.from_path(...)等先上传新对象的三元组公开 URLSDK/APIFileUploadable.from_url(...)新对象的三元组核心就一句话session 文件路径 ≠s3key先把文件变成 Composio 托管的 staging 对象再把它新鲜的传给 toolkit 动作。遵循这条规则就能避免 Tool Router 文件传递中最常见的一类 404 错误。相关背景可继续阅读 Tool Router 会话指南、Remote sandbox 文件与挂载说明 以及本主题的 guide 版本 mcp-tool-router-files.mdx。【免费下载链接】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），仅供参考