Composio Google Analytics 工具包排障指南ToolNotFound 修复、MCP 接入与空报告诊断【免费下载链接】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/composioGoogle Analytics 是 Composio 平台中用于流量、用户行为与转化数据分析的官方工具包但在实际集成中开发者常会遇到三类典型问题工具返回ToolNotFound或工具列表不完整、希望通过 MCP 协议接入分析能力、以及报表工具返回空数据。本文以 Composio 仓库内 Google Analytics 知识库文章docs/kb/articles/toolkits-google-analytics.md为主线结合工具包元数据、版本管理文档与 Proxy Execute 实现给出可复现的修复步骤与诊断方法。读完本文你将掌握如何通过版本参数让 Google Analytics 工具完整暴露、如何在 MCP 配置中选中该工具包以及如何用同参数对比法区分“提供商无数据”与“Composio 调用故障”。一、先认识 Composio 中的 Google Analytics 工具包在动手排障之前先确认工具包的基本事实。仓库内的工具包元数据文件 docs/public/data/toolkits.json 中记录了google_analytics的完整信息sluggoogle_analyticsAPI、SDK 与 MCP 配置中均以此作为工具包标识名称Google Analytics分类analytics认证方式OAUTH2且支持 Composio 托管认证composioManagedAuthSchemes同为OAUTH2工具数量69 个以仓库内该文件为准版本号形如20260721_00的日期版本。工具命名统一采用GOOGLE_ANALYTICS_*前缀例如GOOGLE_ANALYTICS_BATCH_RUN_REPORTS批量运行多个 GA4 报表、GOOGLE_ANALYTICS_BATCH_RUN_PIVOT_REPORTS批量运行透视报表、GOOGLE_ANALYTICS_CHECK_COMPATIBILITY校验所选维度和指标是否兼容、GOOGLE_ANALYTICS_CREATE_AUDIENCE_EXPORT创建受众导出、GOOGLE_ANALYTICS_GET_ACCOUNT按资源名获取账号信息等。理解“工具是分版本暴露的”这一点是定位ToolNotFound问题的前提。二、ToolNotFound 或工具数量偏少优先检查 Toolkit 版本2.1 问题现象当 Google Analytics 工具调用返回ToolNotFound或者通过工具列表 API 只能拿到该工具包的一小部分工具时知识库给出的首要排查方向是当前请求使用的工具包版本过旧见 docs/kb/articles/toolkits-google-analytics.md。老版本或未显式指定版本时的默认版本所暴露的工具数量可能远少于最新版本。2.2 根因默认版本是 base version这个现象不是随机出现的。仓库内的版本管理文档 docs/content/docs/tools-direct/toolkit-versioning.mdx 明确说明v3 API 在不指定版本时默认返回 base version00000000_00这可能导致返回的工具数量比平台 UI 少。需要显式传入toolkit_versionslatest或指定某个具体版本才能拿到新版本工具而 v3.1 的 tools API 则默认返回最新版本。也就是说如果你直接调用工具列表接口而未携带版本参数得到的可能是 base version 的工具子集google_analytics新发布的工具自然“找不到”。2.3 解决方案为工具列表请求显式传入版本参数知识库给出的写法是使用查询参数组合toolkit_versionslatest、toolkit_sluggoogle_analytics并配合较大的limit以便一次取全所有工具GET /api/v3/tools?toolkit_versionslatesttoolkit_sluggoogle_analyticslimit1000对应到 curl完整请求形如参考 toolkit-versioning.mdx 的示例结构# 不带 toolkit_versions可能只返回 base version 下的少量工具 curl https://backend.composio.dev/api/v3/tools?toolkit_sluggoogle_analyticslimit1000 \ -H x-api-key: YOUR_API_KEY # 带 toolkit_versionslatest返回最新版本下的全部 Google Analytics 工具 curl https://backend.composio.dev/api/v3/tools?toolkit_sluggoogle_analyticstoolkit_versionslatestlimit1000 \ -H x-api-key: YOUR_API_KEY说明示例中的 API 地址为当前仓库文档中记录的 v3 工具列表端点。查询参数toolkit_versions、toolkit_slug、limit均可组合使用toolkit_versions可传latest或某个形如YYYYMMDD_NN的具体版本号。版本号遵循YYYYMMDD_NN格式YYYYMMDD是发布日期NN是当日顺序发布序号如20260721_00见 docs/content/docs/tools-direct/toolkit-versioning.mdx。引用工具包元数据时也可直接查看 docs/public/data/toolkits.json 中该条目记录的version字段。2.4 版本解析优先级当多处同时指定版本时解析顺序为见 toolkit-versioning.mdx单次执行版本优先级最高tools.execute()调用中的version参数SDK 初始化版本Composio(...)构造时的toolkit_versions字典环境变量形如COMPOSIO_TOOLKIT_VERSION_GITHUB的按工具包命名的变量。排查“工具数偏少”时除了请求参数还应顺带确认上述任一层级是否把google_analytics钉到了旧版本。三、版本管理的完整配置方式如果只想保证“永远拿到最新工具”或在生产环境中需要稳定钉版可以在不同层级配置。以下代码均出自 docs/content/docs/tools-direct/toolkit-versioning.mdx。3.1 SDK 初始化时钉版本Pythonfrom composio import Composio composio Composio( api_keyYOUR_API_KEY, toolkit_versions{ google_analytics: 20260721_00, # 钉到具体日期版本 } )TypeScriptimport { Composio } from composio/core; const composio new Composio({ apiKey: YOUR_API_KEY, toolkitVersions: { google_analytics: 20260721_00, } });3.2 环境变量export COMPOSIO_TOOLKIT_VERSION_GOOGLE_ANALYTICS20260721_003.3 单次执行覆盖from composio import Composio composio Composio(api_keyYOUR_API_KEY) result composio.tools.execute( GOOGLE_ANALYTICS_BATCH_RUN_REPORTS, arguments{...}, # 具体的 property、dateRanges、dimensions、metrics 等 user_iduser-k7334, version20260721_00 # 仅本次执行生效 )3.4 手动执行时的latest限制重要需要特别留意从 Python SDK v0.9.0、TypeScript SDK v0.2.0 起手动执行tools.execute()时要求显式指定版本且latest不能单独使用。若要手动执行最新版本必须传入dangerously_skip_version_checkTrueTypeScript 为dangerouslySkipVersionCheck: true否则应钉一个具体日期版本见 toolkit-versioning.mdx。该标志的名称本身就是提醒不同版本间工具的输出 schema 可能变化。而在获取工具列表、Session 场景下latest无需该标志即可正常使用。选择建议文档原文的规则如果工具输出由 LLM/Agent 消费用latest如果由你的代码解析例如解构字段、映射到数据库 schema则钉版。绝大多数 Session 化 Agent 工作流默认走latest。四、通过 MCP 接入 Google Analytics知识库第二条明确给出 MCP 接入方式创建一个选中了 Google Analytics 的 MCP 配置或编辑已有 MCP 配置把 Google Analytics 添加为所选工具/工具包然后按 MCP 快速开始流程连接并使用生成的 MCP 配置见 docs/kb/articles/toolkits-google-analytics.md。仓库内可进一步参考的 MCP 相关资料包括docs/content/docs/sessions-via-mcp.mdx通过 MCP 使用 Session 的接入说明docs/content/docs/single-toolkit-mcp.mdx单一工具包的 MCP 配置方式与“只选中 Google Analytics 一个工具包”的场景直接对应docs/api-overviews/mcp.mdxMCP 相关 API 与配置概览docs/content/docs/quickstart.mdxMCP 快速开始的完整流程入口。配置要点是MCP 配置中的工具选择要显式包含google_analytics而不是依赖默认集合——否则可能恰好落在旧版或未包含该工具包的配置上再次复现“工具找不到”的问题。接入后即可按 MCP 通道正常调用GOOGLE_ANALYTICS_*工具。五、空报告排查数据可用性问题还是 Composio 故障5.1 问题现象Google Analytics 报表类工具返回空数据或非预期数据。知识库明确指出这很可能是 Google Analytics 提供商侧的数据可用性或查询问题而不是 Composio 调用失败见 docs/kb/articles/toolkits-google-analytics.md。5.2 标准诊断流程同参数对比法正确的排查姿势是构造一次“等价请求”做对比而不是直接怀疑平台保持参数完全一致相同的 property、date range日期范围、dimensions维度、metrics指标在 Google Analytics 官方界面或官方 API上执行同参数查询或通过 Composio 的 Proxy Execute 发起同参数请求作为第二路对比对比结果若提供商侧同样返回空结果 → 判定为数据可用性或查询本身的问题例如该时间段无数据、维度指标组合不合法、数据尚未处理完成若提供商侧能返回数据而 Composio 工具不能 → 判定为调用链问题需要走升级通道。5.3 为什么用 Proxy Execute 做对比Proxy Execute 是这里的关键辅助手段。根据 docs/content/docs/extending-sessions/proxy-execute.mdx 的说明session.proxyExecute()可以调用会话可达的任意 HTTP 端点由 Composio 在服务端注入认证信息OAuth token、API key 等你的代码永远不需要接触原始凭据。这意味着你可以用与工具相同的账号凭据直接向 Google Analytics 的原始 REST 端点发起请求从而把“工具封装是否有问题”与“提供商是否返回空数据”彻底剥离开。Proxy Execute 的请求结构Python 示例from composio import Composio composio Composio(api_keyyour_api_key) session composio.create(user_123, toolkits[google_analytics]) response session.proxy_execute( toolkitgoogle_analytics, endpoint/v1beta/properties/123456789/runReport, # GA4 Data API 报表端点示例 methodPOST, body{ dateRanges: [{startDate: 2026-07-01, endDate: 2026-07-07}], dimensions: [{name: date}], metrics: [{name: sessions}], }, ) print(response[status]) print(response[data])需要注意的两点安全边界均有仓库文档依据同域限制Proxy Execute 拒绝跨域请求endpoint必须解析到该工具包连接账号所属的同一域名GA 连接只能调用其对应的 Google Analytics API 域名路径这是刻意的安全边界见 proxy-execute.mdx 与 changelog docs/content/changelog/04-24-26-proxy-execute-same-domain.mdx凭据不落代码Proxy Execute 的价值之一就是让你不必把 token 拿出来自己调 API正因如此下面的安全红线才必须强调。5.4 升级渠道与安全红线如果等价提供商请求正常、仅 Composio 工具失败知识库要求联系 Composio 支持提供log ID日志 ID提供一份脱敏后的对比信息redacted comparison。同时有一条不可逾越的安全红线绝不从 connected-account 数据中提取或分享 token。这一点与平台的整体安全策略一致——仓库文档明确指出Composio 默认在 API 响应中对连接账号的 token 做脱敏redacted处理相关能力请走 Proxy Execute见 docs/content/changelog/06-04-26-security-reliability-hardening.mdx 与 docs/content/docs/security/overview.mdx。排查过程本身也不应破坏这一边界对比请求一律经由 Composio 代理注入凭据完成而不是手动导出 token 后直连。六、排障速查表现象首要排查动作关键依据调用返回ToolNotFound工具列表请求带上toolkit_versionslatesttoolkit_sluggoogle_analyticslimit1000docs/kb/articles/toolkits-google-analytics.md工具列表只返回少量 GA 工具检查是否被钉到 base version / 旧版本改用latest或新日期版本docs/content/docs/tools-direct/toolkit-versioning.mdx需要经 MCP 使用 GAMCP 配置中显式选中google_analytics工具/工具包再走 MCP 快速开始docs/kb/articles/toolkits-google-analytics.md报表返回空/异常数据同参数在 GA 官方侧与 Proxy Execute 各跑一遍做对比docs/kb/articles/toolkits-google-analytics.md确认是调用链问题上报 log ID 脱敏对比信息给支持绝不分享 tokendocs/kb/articles/toolkits-google-analytics.md七、小结Google Analytics 工具包在 Composio 上的绝大多数问题根源都不在工具本身ToolNotFound与工具列表残缺本质是版本解析问题——v3 API 默认 base version显式传toolkit_versionslatest即可拿到完整工具集空报告则要先做同参数对比把“提供商数据可用性”与“Composio 调用故障”区分开再用 Proxy Execute 做第二路验证最后带着 log ID 与脱敏对比信息走升级通道。掌握版本参数、MCP 配置选择与对比诊断这三板斧即可稳定落地 Google Analytics 的 Agent 集成。若需深入源码层面的版本解析细节可继续阅读 docs/content/docs/tools-direct/toolkit-versioning.mdx 与 docs/content/docs/extending-sessions/proxy-execute.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），仅供参考