企业官网建设流程全解析

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/composio

Google 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的完整信息：

• slug：google_analytics（API、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 version（00000000_00），这可能导致返回的工具数量比平台 UI 少。需要显式传入toolkit_versions=latest或指定某个具体版本才能拿到新版本工具；而 v3.1 的 tools API 则默认返回最新版本。

也就是说，如果你直接调用工具列表接口而未携带版本参数，得到的可能是 base version 的工具子集，google_analytics新发布的工具自然“找不到”。

2.3 解决方案：为工具列表请求显式传入版本参数

知识库给出的写法是使用查询参数组合toolkit_versions=latest、toolkit_slug=google_analytics，并配合较大的limit以便一次取全所有工具：

GET /api/v3/tools?toolkit_versions=latest&toolkit_slug=google_analytics&limit=1000

对应到 curl，完整请求形如（参考 toolkit-versioning.mdx 的示例结构）：

# 不带 toolkit_versions：可能只返回 base version 下的少量工具 curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=google_analytics&limit=1000' \ -H 'x-api-key: YOUR_API_KEY' # 带 toolkit_versions=latest：返回最新版本下的全部 Google Analytics 工具 curl 'https://backend.composio.dev/api/v3/tools?toolkit_slug=google_analytics&toolkit_versions=latest&limit=1000' \ -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）：

1. 单次执行版本（优先级最高，tools.execute()调用中的version参数）；
2. SDK 初始化版本（Composio(...)构造时的toolkit_versions字典）；
3. 环境变量（形如COMPOSIO_TOOLKIT_VERSION_GITHUB的按工具包命名的变量）。

排查“工具数偏少”时，除了请求参数，还应顺带确认上述任一层级是否把google_analytics钉到了旧版本。

三、版本管理的完整配置方式

如果只想保证“永远拿到最新工具”，或在生产环境中需要稳定钉版，可以在不同层级配置。以下代码均出自 docs/content/docs/tools-direct/toolkit-versioning.mdx。

3.1 SDK 初始化时钉版本

Python：

from composio import Composio composio = Composio( api_key="YOUR_API_KEY", toolkit_versions={ "google_analytics": "20260721_00", # 钉到具体日期版本 } )

TypeScript：

import { Composio } from "@composio/core"; const composio = new Composio({ apiKey: "YOUR_API_KEY", toolkitVersions: { google_analytics: "20260721_00", } });

3.2 环境变量

export COMPOSIO_TOOLKIT_VERSION_GOOGLE_ANALYTICS="20260721_00"

3.3 单次执行覆盖

from composio import Composio composio = Composio(api_key="YOUR_API_KEY") result = composio.tools.execute( "GOOGLE_ANALYTICS_BATCH_RUN_REPORTS", arguments={...}, # 具体的 property、dateRanges、dimensions、metrics 等 user_id="user-k7334", version="20260721_00" # 仅本次执行生效 )

3.4 手动执行时的latest限制（重要）

需要特别留意：从 Python SDK v0.9.0、TypeScript SDK v0.2.0 起，手动执行tools.execute()时要求显式指定版本，且latest不能单独使用。若要手动执行最新版本，必须传入dangerously_skip_version_check=True（TypeScript 为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.mdx：MCP 相关 API 与配置概览；
• docs/content/docs/quickstart.mdx：MCP 快速开始的完整流程入口。

配置要点是：MCP 配置中的工具选择要显式包含google_analytics，而不是依赖默认集合——否则可能恰好落在旧版或未包含该工具包的配置上，再次复现“工具找不到”的问题。接入后即可按 MCP 通道正常调用GOOGLE_ANALYTICS_*工具。

五、空报告排查：数据可用性问题还是 Composio 故障？

5.1 问题现象

Google Analytics 报表类工具返回空数据或非预期数据。知识库明确指出：这很可能是 Google Analytics 提供商侧的数据可用性或查询问题，而不是 Composio 调用失败（见 docs/kb/articles/toolkits-google-analytics.md）。

5.2 标准诊断流程：同参数对比法

正确的排查姿势是构造一次“等价请求”做对比，而不是直接怀疑平台：

1. 保持参数完全一致：相同的 property、date range（日期范围）、dimensions（维度）、metrics（指标）；
2. 在 Google Analytics 官方界面（或官方 API）上执行同参数查询；
3. 或通过 Composio 的 Proxy Execute 发起同参数请求，作为第二路对比；
4. 对比结果：
   • 若提供商侧同样返回空结果 → 判定为数据可用性或查询本身的问题（例如该时间段无数据、维度指标组合不合法、数据尚未处理完成）；
   • 若提供商侧能返回数据而 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_key="your_api_key") session = composio.create("user_123", toolkits=["google_analytics"]) response = session.proxy_execute( toolkit="google_analytics", endpoint="/v1beta/properties/123456789/runReport", # GA4 Data API 报表端点示例 method="POST", 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 工具失败，知识库要求：

1. 联系 Composio 支持；
2. 提供log ID（日志 ID）；
3. 提供一份脱敏后的对比信息（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 后直连。

六、排障速查表

七、小结

Google Analytics 工具包在 Composio 上的绝大多数问题，根源都不在工具本身：ToolNotFound与工具列表残缺，本质是版本解析问题——v3 API 默认 base version，显式传toolkit_versions=latest即可拿到完整工具集；空报告则要先做同参数对比，把“提供商数据可用性”与“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