Composio Excel Toolkit 实战指南2D 数组传参、SharePoint 工作簿操作与 Microsoft 认证配置【免费下载链接】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/composioExcel 是 Composio 平台中面向电子表格场景的核心 toolkit提供 54 个基于 Microsoft Graph API 的工具动作覆盖工作簿创建、读写区域、工作表管理、图表与表格操作、PDF 导出等能力。本文以 Composio 知识库中 Excel 的公开支持文档docs/kb/source/toolkits/excel/public.md为主线结合仓库中的 toolkit 元数据docs/public/data/toolkits.json与 CLI 工具枚举ts/packages/cli/test/mocks/tools-as-enums.json系统讲解正确的传参格式、SharePoint 工作簿操作方式、Microsoft 认证配置与工具 schema 升级要点。读完本文你将能够为 Agent 正确编写 Excel 动作参数、定位EXCEL_GET_RANGE失败根因并保持认证与工具版本处于可用状态。一、EXCEL_UPDATE_RANGE的 values 必须是二维数组在调用 Composio 的EXCEL_UPDATE_RANGEUpdate Range动作写入单元格数据时values参数必须是一个二维数组外层列表代表行row每个内层列表按顺序存放该行各列cell的值。即使只写入一个单元格也需要双重包裹。正确示例——写入单个单元格92{ values: [[92]] }错误示例——仅用一层数组{ values: [92] }二维数组结构与 Excel 区域range的行列模型天然对应假设要一次性写入 2 行 3 列的数据应该这样组织{ values: [ [Name, Region, Amount], [Alice, APAC, 1200] ] }这也是微软 Graph APIupdateRange对values的语义要求——该动作在仓库元数据中的描述即为 Update a range in a worksheet using Microsoft Graph API见 docs/public/data/toolkits.json 中EXCEL_UPDATE_RANGE条目。Agent 在生成参数时若按 JSON 数组的直觉只包一层就会导致写入失败这是 Excel 工具使用中最常见的输入错误之一。二、Excel 上传类工具接受结构化工作簿数据新版 Excel 工具形态不再要求调用方或 LLM 直接提供二进制工作簿内容而是改为接受结构化数据由工具在服务端先生成.xlsx文件再执行上传。核心参数是两个列表/字典worksheet_names要创建工作表的名称列表worksheet_data与工作表名称对应的数据内容列表或字典工具据此填充单元格。典型调用形如{ worksheet_names: [Sales, Inventory], worksheet_data: { Sales: [ [Product, Q1, Q2], [Widget, 100, 130] ], Inventory: [ [SKU, Stock], [W-001, 42] ] } }这种设计的收益是双重的对 LLM 而言生成 JSON 结构化数据远比生成二进制.xlsx可靠对调用方而言也无需自行处理 Excel 文件格式。仓库元数据中EXCEL_CREATE_WORKBOOK的描述印证了这条链路Creates a new Excel workbook file at a specified drive path. Generates a new .xlsx file with specified worksheets and data, then uploads it to OneDrive.见 docs/public/data/toolkits.json。与之配套的还有EXCEL_UPLOAD_WORKBOOK从 URL 下载外部 Excel 文件并上传到 OneDrive/SharePoint两者共同覆盖了新建上传与外部文件导入两条路径。三、EXCEL_GET_RANGE失败排查sheet 名与 item_id 不匹配当EXCEL_GET_RANGEGet Range看起来失败但工具本身工作正常时优先核对两个参数工作表名称worksheet name确认工作簿中确实存在所请求的工作表例如默认的Sheet1。名称大小写、末尾空格都会导致匹配失败。工作簿文件 IDitem_id确认传入的item_id是目标工作簿的正确文件 ID而不是其他文件的 ID例如误传了目录 ID 或另一个工作簿的 ID。从源码结构看EXCEL_GET_RANGE与EXCEL_GET_WORKSHEET按名称或 ID 获取工作表、EXCEL_GET_WORKSHEET_USED_RANGE不指定固定地址、自动读取活动数据区域属于同一组基于 Microsoft Graph API 的读取动作其中EXCEL_GET_WORKSHEET_USED_RANGE还支持valuesOnly选项以过滤仅有格式的空单元格见 docs/public/data/toolkits.json。排查EXCEL_GET_RANGE问题时可以先调用EXCEL_GET_WORKBOOK检查工作簿包含的工作表清单再核对item_id从而把参数不匹配与真实 API 错误区分开。四、SharePoint 场景工作簿操作一律使用 Excel toolkit 动作对于存放在 SharePoint 上的 Excel 文件工作簿操作应该使用 Excel toolkit 的动作而不是直接调用 SharePoint 文件 API。原因是 Excel toolkit 动作本身是 Excel API走 Microsoft Graph 的 Excel 端点能正确处理会话、区域与工作表语义而 SharePoint 文件操作只负责文件级的管理。Composio 支持团队已确认以下动作对剩余 Excel 使用场景可用原文见 docs/kb/source/toolkits/excel/public.md动作作用EXCEL_CLOSE_SESSION显式结束持久会话释放工作簿锁EXCEL_DELETE_WORKSHEET从工作簿中删除工作表EXCEL_UPDATE_WORKSHEET更新工作表属性名称、位置EXCEL_UPDATE_RANGE更新工作表中某个区域的数据以EXCEL_CLOSE_SESSION为例仓库元数据给出了非常有价值的实现细节docs/public/data/toolkits.jsonGraph 的closeSessionAPI 是幂等的对活跃会话与已关闭会话都返回 204因此该动作会先通过refreshSession校验会话有效性对无效或已关闭的会话返回明确错误以提供更清晰的用户反馈。这也提醒我们在多次连续写操作结束后显式关闭会话可以避免工作簿锁长期占用。此外Excel toolkit 还单独提供了一批 SharePoint 专属动作如EXCEL_ADD_SHAREPOINT_WORKSHEET、EXCEL_GET_SHAREPOINT_RANGE、EXCEL_UPDATE_SHAREPOINT_RANGE它们走 Microsoft Graph Sites API供需要直接面向 SharePoint 站点内工作簿的场景使用。五、认证配置共用 Microsoft 认证指南Excel 的认证设置沿用 Composio 的 Microsoft 认证指南即 auth/outlook 指南同一份指南同样适用于 SharePoint、Microsoft Teams、Outlook 与 Excel。这意味着如果你已经为 Outlook 或 SharePoint 配置过 Microsoft OAuth那么 Excel 的认证配置模式完全一致无需单独学习另一套流程。从仓库的 toolkit 元数据docs/public/data/toolkits.json可以看到 Excel 支持两种认证方案1. OAUTH2excel_oauth——授权码流程适用于以用户身份访问其 OneDrive/Excel 文件必填client_id应用客户端 ID、client_secret客户端密钥可选oauth_redirect_uri默认回调地址需加入应用 OAuth 允许列表、scopes默认Files.ReadWrite,Sites.ReadWrite.All,offline_access,User.Read连接发起时可选的issuer字段用于指定 Microsoft Entra 租户别名/ID/域默认common即面向多租户的公共端点。2. S2S_OAUTH2excel_s2s_oauth2——服务到服务client credentials流程适用于后台服务以应用身份访问必填client_idEntra 应用注册的 Application ID、client_secretCertificates Secrets 中生成的密钥、generic_idMicrosoft Entra 租户 IDGUID 格式无其他可选字段。选择建议Agent 代表终端用户操作其个人 Excel 文件时用 OAUTH2后台服务在组织租户内以应用身份批量操作时用 S2S_OAUTH2。注意知识库还提示Excel 对 OAuth2 client credentials 的支持可能因动作而异见 docs/content/kb/guide/toolkits-excel.mdx 的 keywords 列表接入前应针对目标动作确认其认证模式。六、schema 升级规避被模型提供商拒绝的 dollar-sign 参数历史版本中部分 Excel 动作 schema 曾暴露带$前缀的顶层参数名例如形如$top、$select这类 OData 风格参数。这类参数名会被不少模型提供商的工具调用校验直接拒绝导致 Agent 无法正常调用动作。处理方式升级到最新的可用 release。当前 schema 已不再使用这些非法的顶层参数名。如果你的 Agent 在调用某个 Excel 动作时频繁收到参数名非法之类的报错优先检查当前使用的 SDK 与后端版本并升级到最新版本后再重试。仓库中 Excel toolkit 的版本信息如20260828_00见 docs/public/data/toolkits.json可用于核对当前发布版本。七、列格式化与换行支持确认当前 toolkit 版本通用列格式化column formatting与列换行column wrapping及相关工作表操作在当前版本的 Excel toolkit 中均已可用。如果你在动作 schema 中找不到这些能力说明使用的 toolkit 版本过旧切换到最新 toolkit 版本即可。这一点与上一条dollar-sign 参数问题共同指向同一个运维实践保持 Excel toolkit 处于最新版本。较新的版本既修复了 schema 兼容性问题也持续补齐工作表格式化类能力是避免动作在文档上存在、但当前 schema 里找不到这类偏差的最直接手段。八、Excel 动作速查54 个工具能力概览根据仓库元数据Excel toolkitslug 为excel当前共暴露54 个工具、0 个触发器归类于 spreadsheets 分类见 docs/public/data/toolkits.json。除前文涉及的读写与会话动作外常见能力还包括工作簿级EXCEL_CREATE_WORKBOOK新建并上传、EXCEL_UPLOAD_WORKBOOKURL 导入、EXCEL_EXPORT_WORKBOOK_TO_PDFPDF 导出、EXCEL_ADD_WORKBOOK_PERMISSION按邀请分享工作簿工作表级EXCEL_ADD_WORKSHEET、EXCEL_DELETE_WORKSHEET、EXCEL_UPDATE_WORKSHEET、EXCEL_GET_WORKSHEET_USED_RANGE区域级EXCEL_CLEAR_RANGE清空值/格式/内容、EXCEL_INSERT_RANGE插入区域并下移/右移既有单元格、EXCEL_UPDATE_RANGE、EXCEL_GET_RANGE表格级EXCEL_ADD_TABLE、EXCEL_ADD_TABLE_COLUMN/ROW、EXCEL_APPLY_TABLE_FILTER、EXCEL_APPLY_TABLE_SORT、EXCEL_CONVERT_TABLE_TO_RANGE图表级EXCEL_ADD_CHART、EXCEL_GET_CHART_AXIS、EXCEL_GET_CHART_LEGEND、EXCEL_UPDATE_CHART_LEGEND等。这些动作名同时出现在 CLI 工具枚举 mock 中ts/packages/cli/test/mocks/tools-as-enums.json说明 CLI 层同样以这些枚举名路由 Excel 工具Agent 在编写工具调用时可放心使用上述 slug。总结Excel 工具链的使用要点把上述要点收敛为一份可执行的检查清单写数据values永远传二维数组单单元格也要[[92]]双重包裹建/传文件优先使用worksheet_namesworksheet_data结构化数据由工具服务端生成.xlsx读数据报错先查item_id是否指向目标工作簿再查工作表名如Sheet1是否存在且拼写一致SharePoint 文件工作簿操作走 Excel toolkit 动作Excel API文件级操作才走 SharePoint 文件接口连续写入后记得EXCEL_CLOSE_SESSION释放锁认证统一参考 Microsoft auth 指南按场景在 OAUTH2用户态与 S2S_OAUTH2应用态之间选择版本遇到$前缀参数被拒或找不到列格式化/换行能力时升级到最新 toolkit 版本。【免费下载链接】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），仅供参考