Composio × Google ADK 集成指南：将 1000+ 工具桥接为 FunctionTool 的实战方案

Composio × Google ADK 集成指南将 1000 工具桥接为 FunctionTool 的实战方案【免费下载链接】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-google-adk是 Composio 官方为 Google ADKAgent Development Kit提供的适配层它把 Composio 生态中的 1000 应用工具逐个包装成 Google ADK 的FunctionTool对象让你的 Gemini 智能体可以直接以原生函数调用function calling的方式执行 GitHub、Gmail、Slack 等真实业务操作。本文以 python/providers/google_adk/README.md 为主线深入讲解安装配置、Quickstart 代码、多轮会话复用以及GoogleAdkProvider底层“schema → Python 签名/docstring → FunctionTool”的完整包装链路与源码实现帮助你快速上手并理解其工作原理。一、composio-google-adk 是什么composio-google-adk是 Composio 为 Google ADK 框架提供的官方适配器。它解决的核心问题是Google ADK 的Agent只能消费google.adk.tools.FunctionTool形式的函数声明而 Composio 管理的 1000 应用工具toolkits并不天然具备该形态。通过本包二者得以无缝对接工具形态转换每个 Composio 工具被转换为FunctionToolADK 可将其作为普通函数声明传递给 Gemini 模型会话级工具作用域每个 Composio 会话session绑定一个真实用户工具执行时自动携带该用户的连接凭证类型安全SDK 泛型自动推断为Composio[FunctionTool, list[FunctionTool]]在 mypy 等类型检查器下可直接获得类型提示保障。包的元信息可在 python/providers/google_adk/pyproject.toml 与 python/providers/google_adk/setup.py 中确认包名composio-google-adk导入名composio_google_adk当前仓库版本 0.21.1要求 Python 3.10, 4核心依赖为google-adk2.5.0与composio。二、安装与密钥配置按官方 README 安装三个包pip install composio composio-google-adk google-adk安装完成后需要配置两类密钥通过环境变量注入COMPOSIO_API_KEY从 Composio Dashboard 的 Settings 页面获取用于调用 Composio 后端获取工具列表与执行工具GOOGLE_API_KEYGoogle Gemini API 密钥用于 ADK 驱动 Gemini 模型完成推理与函数调用。SDK 层面对COMPOSIO_API_KEY的处理可在 python/composio/sdk.py 中看到Composio.__init__会优先取构造参数中的api_key否则回退到环境变量COMPOSIO_API_KEY两者都缺失时抛出ApiKeyNotProvidedError。此外还支持COMPOSIO_BASE_URL等环境变量便于自托管部署场景。三、Quickstart从零构建一个能执行 GitHub 操作的 ADK 智能体3.1 完整代码来自官方 READMEfrom composio import Composio from composio_google_adk import GoogleAdkProvider from google.adk.agents import Agent from google.adk.runners import Runner from google.adk.sessions import InMemorySessionService from google.genai import types composio Composio(providerGoogleAdkProvider()) # Each Composio session is scoped to one of your users composio_session composio.create(user_iduser_123) tools composio_session.tools() agent Agent( namepersonal_assistant, modelgemini-2.0-flash, instructionYou are a helpful assistant. Use Composio tools to take action., toolstools, ) session_service InMemorySessionService() session_service.create_session_sync( app_namepersonal_assistant, user_iduser_123, session_id1234, ) runner Runner( agentagent, app_namepersonal_assistant, session_servicesession_service, ) events runner.run( user_iduser_123, session_id1234, new_messagetypes.Content( roleuser, parts[types.Part(textStar the repository composiohq/composio on GitHub)], ), ) for event in events: if event.is_final_response() and event.content and event.content.parts: print(event.content.parts[0].text)3.2 代码拆解初始化 SDK 并指定适配器Composio(providerGoogleAdkProvider())。传入 provider 后SDK 的泛型参数自动推断为FunctionTool/list[FunctionTool]参见 python/tests/test_type_inference_google_adk.py该文件被 mypy 静态分析以验证类型推断正确性。创建会话composio.create(user_iduser_123)。每个 Composio 会话对应一个最终用户工具的鉴权与执行都绑定在该用户维度上。从源码看composio.create与composio.use是composio.sessionsToolRouter的顶层快捷方式python/composio/sdk.py。拉取会话级工具composio_session.tools()返回list[FunctionTool]即已按 ADK 格式包装好的工具集合python/composio/core/models/tool_router_session.py。组装 ADK 智能体将工具列表直接传入Agent(..., toolstools)模型选用gemini-2.0-flash并在 instruction 中明确告知模型使用 Composio 工具采取行动。建立会话与 RunnerInMemorySessionService提供进程内会话存储Runner负责驱动 agent 执行。运行runner.run(...)以用户消息启动一轮对话遍历返回的 events取is_final_response()的最终文本打印。示例中模型会识别“Star the repository composiohq/composio on GitHub”这一意图通过FunctionTool调用 Composio 的 GitHub 工具完成真实操作。仓库中还提供了一个同思路的可运行脚本 python/providers/google_adk/google_adk_demo.py其区别在于通过composio.tools.get(user_iduser_id, toolkits[GITHUB])显式指定 GITHUB 工具包且最终响应判断更完整额外校验content.parts非空。四、多轮对话用 session_id 复用会话README 明确指出多轮场景下不要再次调用create()而应保存composio_session.session_id并用composio.use(session_id)复用。# 第一轮创建会话并保存 id composio_session composio.create(user_iduser_123) session_id composio_session.session_id # 后续轮次复用已有会话 composio_session composio.use(session_idsession_id) tools composio_session.tools()这背后的语义是create()会为指定user_id创建全新的工具会话上下文重复创建既浪费后端资源也无法延续前一轮对话中建立/授权的连接状态use()则按会话 ID 恢复既有上下文保留连接、工具配置与文件等会话内状态。底层实现参见 python/composio/core/models/tool_router.py其中use()还支持传入custom_tools/custom_toolkits将 SDK 本地自定义工具绑定到会话中。此外create()本身支持丰富的会话配置python/composio/core/models/tool_router.py例如toolkits启用/禁用工具包如[github, slack]或{enable: [github]}tools按工具包细粒度控制具体工具如{gmail: [GMAIL_SEND_EMAIL, GMAIL_SEARCH]}tags按标签readOnlyHint、destructiveHint、idempotentHint、openWorldHint过滤工具connected_accounts为工具包预绑定连接账户如{github: ca_xxx}auth_configs指定认证配置 ID如{github: ac_xxx}。这些参数均可用于create(user_id..., **配置)精细控制会话内可用工具范围。五、原理深挖GoogleAdkProvider 如何把工具包成 FunctionTool5.1 包装流程总览GoogleAdkProvider继承自AgenticProvider[FunctionTool, list[FunctionTool]]python/providers/google_adk/composio_google_adk/provider.py并注册了 provider 名称google_adk。基类AgenticProvider定义了两个抽象方法wrap_tool/wrap_toolspython/composio/core/provider/agentic.pyGoogle ADK 适配器对二者分别实现wrap_tools只是对wrap_tool的批量调用。单个工具的包装流程为取出工具输入 JSON Schematool.input_parametersalias_tool_input_schema将 Schema 属性名别名化为合法的 Python 参数名依据属性 Schema 的描述生成带Args:/Returns:段的 docstring构造执行闭包_execute先restore_arguments还原原始参数名再经normalize_tool_arguments防御性归一化后调用execute_tool用function_signature_from_jsonschema生成inspect.Parameter列表并覆写函数的__signature__、__annotations__与__doc__最终以FunctionTool(function)返回供 ADK 使用。5.2 Schema 别名化兼容 Python 标识符Composio 工具的输入 Schema 字段名未必是合法 Python 标识符例如含连字符、或与 Python 关键字冲突如from。alias_tool_input_schemapython/composio/utils/shared.py会做深度拷贝、内联内部$ref引用并将属性名转换为安全的 Python 参数名Python 关键字保留历史后缀_rs如from→from_rs其他无法作为标识符的名字转为 Pydantic 安全标识符长别名截断到 64 字符以兼容 Anthropic 风格工具 Schema 校验器若两个属性映射到同一别名抛出InvalidSchemaError而非静默猜测。包装器记录aliases反向映射执行时用restore_arguments把模型传入的别名参数还原为后端真实字段名python/composio/utils/shared.py。5.3 签名生成JSON Schema → inspect.Parameterfunction_signature_from_jsonschemapython/composio/utils/openapi.py遍历 Schema 的properties将oneOf/anyOf/allOf/type映射为对应的 Python 类型注解构造inspect.ParameterPOSITIONAL_OR_KEYWORD类型。参数默认值遵循以下规则必填参数出现在required中或开启skip_default时默认值置为inspect.Parameter.empty否则使用 Schema 中的default。适配器类上声明了__schema_skip_defaults__ Truepython/providers/google_adk/composio_google_adk/provider.py其语义在基类 python/composio/core/provider/base.py 中定义即默认跳过 Schema 中的默认值让 ADK/Gemini 显式传入每个参数避免模型依赖隐含默认值导致行为不一致。生成后适配器用types.FunctionType复制执行闭包并设置函数名tool.slug再通过setattr覆写__signature__与__annotations__返回类型固定为dict最后写入 docstring——这样 ADK 在构建FunctionTool时即可拿到完整的函数声明名称、参数类型、文档并原样传递给 Gemini 作为 function declaration。5.4 执行与防御性参数归一化包装出的函数在被 ADK 调用时执行_execute(**kwargs)def _execute(**kwargs): kwargs aliases.restore_arguments(kwargs) return execute_tool( slugtool.slug, argumentsnormalize_tool_arguments(kwargs) )normalize_tool_argumentspython/composio/utils/shared.py是每个 provider 共用的参数归一化入口None转为{}模型对无参工具可能不传参数字符串会被 JSON 解析空串转{}无法解析为 dict 的输入list、原始类型、非对象 JSON抛出InvalidParams。这从底层防御了模型偶尔以 JSON 字符串形式输出参数导致执行失败的问题仓库中对应 issue #2406 的修复。执行结果遵循AgenticProviderExecuteFn协议python/composio/core/provider/agentic.py返回含data、error、successful三个键的字典。5.5 类型推断保障python/tests/test_type_inference_google_adk.py 通过assert_type(tools, list[FunctionTool])静态验证了四种获取工具的方式toolkits、slug、tools列表、search以及无显式注解时的自动推断全部指向list[FunctionTool]。这意味着在接入 ADK 时IDE 与类型检查器能够对工具列表给出可靠的类型提示杜绝“工具传不进去”之类的隐式错误。六、安装运行环境与版本前提Python 版本3.10,4见 python/providers/google_adk/pyproject.toml依赖版本google-adk2.5.0、composio当前仓库主 SDK模型要求示例使用gemini-2.0-flash需配置可用的GOOGLE_API_KEY运行前提联网访问 Composio 后端或自托管COMPOSIO_BASE_URL且目标应用如 GitHub的用户连接已授权工具执行才能携带有效凭证。七、小结composio-google-adk的价值在于用极少的胶水代码打通了 Google ADK 与 Composio 工具生态创建用户会话 → 拉取FunctionTool工具列表 → 注入Agent→ 由 Runner 驱动执行。其底层GoogleAdkProvider通过 JSON Schema 别名化、Python 签名生成、docstring 构造与参数归一化四步把每个 Composio 工具稳健地适配为 ADK 原生函数声明配合session_id复用机制可平滑支撑多轮对话与长时间运行的智能体应用。如果想快速验证可直接参考仓库中的 python/providers/google_adk/google_adk_demo.py 脚本在配置好两个密钥后运行体验“一句话让 Gemini 通过 Composio 完成真实 GitHub 操作”的完整链路。【免费下载链接】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），仅供参考