Google ADKadk-pythonIntegrations 集成架构指南可选依赖、懒加载与子包贡献规范【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python本篇技术指南围绕 src/google/adk/integrations/README.md 展开系统讲解 ADK 中集成Integrations目录的定位、设计原则与扩展方式什么代码应该放进integrations/、如何用可选依赖extras保持核心框架轻量、如何通过懒加载给出友好的错误提示以及如何为外部服务Agent Registry、BigQuery、Slack、Redis 等编写自包含的集成子包。读完本文你将掌握在 adk-python 中新增或使用一个集成模块的完整路径并能在源码层面理解其背后的依赖管理与加载机制。Integrations 目录的定位可扩展的插槽式架构ADKAgent Development Kit采用 code-first 的方式构建、评估与部署 AI Agent。随着生态的扩展Agent 往往需要连接外部工具与服务Agent Registry、BigQuery、ApiHub、Slack、Redis……。如果把这些第三方依赖直接打进核心包会让轻量的核心变得臃肿也会给只使用基础能力的用户带来不必要的安装负担。为此adk-python 在 src/google/adk/integrations/ 下划出了一块专门的集成区所有与外部系统对接的模块都应放入该目录的子包中。这一集中化管理带来两个直接好处可发现性开发者可以在一处浏览、查找、复用所有官方集成可贡献性第三方集成有明确、统一的落位与规范社区贡献者更容易参与。从源码结构看当前仓库的integrations/下已经存在 21 个集成子包覆盖 Google Cloud 服务与第三方生态集成子包主要职责agent_identity基于 Google Cloud 的身份凭证与 AuthProvider 方案agent_registry对接 Google Cloud Agent Registry注册/发现 Agent 与 MCP Serverapi_registry对接 API Registry管理 API 元数据bigqueryBigQuery 查询、元数据、搜索与数据洞察工具集cloud_runCloud Run 部署相关能力crewai与 CrewAI 工具生态的互操作daytona/e2b远程沙箱环境DaytonaEnvironment / E2BEnvironmenteventarcEventarc 事件发布与消息工具firestore/gcs/redis持久化存储Firestore、GCS、Redis 会话服务langchain与 LangChain 工具/结构的互操作livekitLiveKit 实时音视频媒体接入model_armorGoogle Cloud Model Armor 安全防护集成ociOracle Cloud Infrastructure 生成式 AIOCIGenAILlmparameter_manager/secret_managerGCP 参数与密钥管理skill_registryGCP Skill RegistryslackSlackRunner将 Agent 部署到 SlackSocket Modevmaas漏洞管理相关集成以上清单依据 src/google/adk/integrations/ 目录实测列出可作为什么代码属于这里的具体参照。什么属于 Integrations 目录原文档给出了两条判断标准实践中可进一步细化连接外部服务的代码凡是把 ADK 与其它服务、API 或工具连接起来的模块例如 agent_registry/agent_registry.py 中直接对https://agentregistry.googleapis.com/v1发起 REST 请求的AgentRegistry客户端都天然属于此目录。依赖第三方库的模块模块若依赖未包含在 ADK 核心依赖中的第三方库例如 Slack 集成依赖slack-bolt、Redis 集成依赖redis、Agent Registry 依赖a2a-sdk也必须放在这里而不能进入核心包。反过来与外部系统无关的通用能力如 Agent 核心逻辑、Runner、会话服务基类、事件模型等应留在src/google/adk/下对应的核心子包中如agents/、runners.py、sessions/不要把通用代码放进integrations/。贡献指南详解五个必须遵守的规范原文档给出的贡献指南是集成开发的核心约束以下结合仓库源码逐条展开。1. 自包含包每个集成一个独立子目录每个集成应独立存在于自己的子目录中例如integrations/my_service/。这样做的目的是保证集成的边界清晰它可以独立安装、独立测试、独立演进不会与其它集成产生隐式耦合。仓库中的 integrations/slack/、integrations/redis/、integrations/bigquery/ 等都是这一模式的实例每个目录内部都有自己的__init__.py与实现文件且大多附带独立的 README如 integrations/slack/README.md、integrations/redis/README.md。2. 内部结构自由不强制遵循核心框架的组织模式集成子包内部可以自由选择自己的代码结构与设计模式无需严格照搬核心 ADK 框架的组织方式。例如integrations/redis/ 内部采用_config.py_redis_session_service.py的下划线私有模块命名用 Pydantic 配置类承载连接参数integrations/agent_registry/ 则用单个agent_registry.py文件承载一个功能完整的高层客户端类integrations/bigquery/ 拆分为client.py、config.py、query_tool.py、metadata_tool.py、search_tool.py等多个工具文件。可见只要保持子包自包含内部是采用扁平单文件、工具拆分、还是配置与实现分离完全由集成作者根据服务复杂度自行决定。3. 依赖可选化extras 是核心原则为了保持 ADK 核心轻量集成所需依赖必须是可选的并通过pyproject.toml中的optional-dependencies即 pip 的 extras定义。extra 的名称应与集成目录名一致用户通过pip install google-adk[my_service]安装。查看仓库根目录的 pyproject.toml可以看到大量与集成目录一一对应的 extras 定义例如optional-dependencies.slackslack-bolt1.22与aiohttp!3.14.2Socket Mode 适配器依赖 aiohttpoptional-dependencies.redisredis4.2注释说明 4.2 是redis.asyncio落地的版本optional-dependencies.a2aa2a-sdk[http-server]0.3.4,2Agent Registry 与远程 A2A Agent 需要optional-dependencies.livekitlivekit、livekit-api与pillow后者用于对入站视频帧做 JPEG 编码optional-dependencies.ocioci2.126optional-dependencies.bigquery-analyticsgoogle-cloud-bigquery、google-cloud-storage与pyarrow注释说明 pyarrow 体积约占该 extra 安装体积的三分之一因此单独拆分optional-dependencies.gcp、mcp、tools、extensions等聚合类 extra。此外optional-dependencies.all是解锁所有运行时特性的集合pyproject.toml中明确排除了 benchmark、community、dev、docs、test 这类服务于构建/测试/文档自身的 extra。需要一次装齐所有集成能力时可以使用pip install google-adk[all]注意all包含crewai[tools]这类带 Python 版本条件仅 3.11~3.12的依赖实际安装时 pip 会按解释器版本自动过滤。4. 懒加载捕获 ModuleNotFoundError 并给出可操作的错误提示集成代码必须实现懒加载。如果用户未安装对应 extras 就使用该集成应当捕获ModuleNotFoundError并抛出带有正确安装命令的描述性错误。这一规范在 integrations/slack/slack_runner.py 中有教科书级的实现try: from slack_bolt.adapter.socket_mode.aiohttp import AsyncSocketModeHandler from slack_bolt.app.async_app import AsyncApp except ImportError as e: raise ImportError( slack_bolt is not installed. Please install it with pip install google-adk[slack]. ) from e同样的模式也出现在 integrations/agent_registry/agent_registry.py 中其错误信息为raise ImportError( AgentRegistry requires the a2a-sdk package. Please install it using pip install google-adk[a2a]. ) from e这里有两个值得借鉴的细节使用from e保留原始异常链raise ... from e方便调试时追溯根因错误信息直接给出精确的安装命令pip install google-adk[extra]把用户引导到正确的操作上而不是抛出一个模糊的ModuleNotFoundError: No module named slack_bolt。这种延迟 import 友好报错的组合让核心包可以安全地不依赖任何第三方库同时保证用户在误用时第一时间得到解决方案。5. 文档每个集成都要有清晰的 setup / configuration / usage 说明每个集成都应提供清晰文档包含安装、配置与使用示例。仓库中的集成子包大多遵循这一要求其中integrations/slack/README.md 覆盖了前置安装、Slack App 的 Socket Mode/权限/事件订阅配置步骤以及一段可运行的SlackRunner接入代码integrations/redis/README.md 则提供了配置参数表、三种连接方式示例URI、独立连接参数、预配置客户端、Redis key 结构说明与直接调用RedisSessionService的完整代码。写作文档时建议沿用这一结构先讲装什么extras 安装命令再讲外部服务怎么配如 Slack App 权限、GCP IAM最后给最小可用示例。实战一把 Agent 部署到 Slack以 SlackRunner 为例作为使用一个集成的完整示例integrations/slack/README.md 展示了如何把 ADK Agent 通过 Socket Mode 部署到 Slack。整体分四步。第一步安装带 Slack 支持的 ADKpip install google-adk[slack]第二步在 Slack API Dashboard 配置 App打开Socket Mode启用后生成App-Level Token以xapp-开头并确保其具有connections:write权限在OAuth Permissions中添加 Bot Token Scopesapp_mentions:read接收 提及、chat:write发送消息、im:history响应私信按需添加groups:history私密频道与channels:history公开频道在Event Subscriptions中启用事件订阅添加 bot 事件app_mention与message.im将 App 安装到工作区获得Bot User OAuth Token以xoxb-开头。第三步初始化并启动 SlackRunnerimport asyncio import os from google.adk.runners import Runner from google.adk.integrations.slack import SlackRunner from slack_bolt.app.async_app import AsyncApp async def main(): # 1. 初始化 ADK Runner传入你的 agent # runner Runner(agentmy_agent, session_servicemy_session_service) # 2. 用 Bot Token 初始化 Slack AsyncApp slack_app AsyncApp(tokenos.environ[SLACK_BOT_TOKEN]) # 3. 初始化 SlackRunner slack_runner SlackRunner(runnerrunner, slack_appslack_app) # 4. 用 App Token 以 Socket Mode 启动 await slack_runner.start(app_tokenos.environ[SLACK_APP_TOKEN]) if __name__ __main__: asyncio.run(main())第四步理解内部的会话与消息处理机制从 integrations/slack/slack_runner.py 的源码可以看到几个关键设计防循环message事件处理器会跳过带bot_id/bot_profile的消息避免 Agent 与自己对话造成死循环触发条件仅当channel_type im私信或消息处于线程中thread_ts存在时才交由_handle_message处理与 README 中订阅app_mention与message.im的配置相呼应会话 ID 规则与 README 的 Session Management 小节一致私信直接以channel_id作为会话 ID线程以f{channel_id}-{thread_ts}作为会话 ID维持线程上下文App 提及且不在线程中以消息时间戳ts作为thread_ts从而开启一个新线程会话流式体验先发送_Thinking..._占位消息随后在runner.run_async(...)的流式事件中用chat_update把占位消息原地替换为 Agent 输出thinking_ts置空后再用say发后续内容结束后若没有文本输出则chat_delete删除占位消息错误兜底run_async抛出异常时把Sorry, I encountered an error: ...写入占位消息或直接回复同时logger.exception记录堆栈。实战二用 Redis 做持久化会话以 RedisSessionService 为例另一个典型的配置项丰富的集成是 Redis 会话服务其完整文档见 integrations/redis/README.md。它实现了BaseSessionService为 Agent 提供基于 Redis 的持久化会话存储。安装pip install google-adk redis最小接入from google.adk.agents import Agent from google.adk.integrations.redis import RedisSessionService from google.adk.integrations.redis import RedisSessionServiceConfig from google.adk.runners import Runner config RedisSessionServiceConfig( uriredis://localhost:6379/0, ttl_seconds86400 * 7, # 7 天 ) session_service RedisSessionService(configconfig) agent Agent( nameassistant, instructionsYou are a helpful AI assistant., ) runner Runner( app_namemy_app, agentagent, session_servicesession_service, )配置参数表来自 README字段默认值可直接照用字段类型默认值说明uriOptional[str]NoneRedis 连接 URI如redis://[:password]host:port/dbSSL 用rediss://。设置后优先于独立连接字段。hostOptional[str]localhostRedis 主机名。portOptional[int]6379Redis 端口。passwordOptional[str]NoneRedis 认证密码。sslboolFalse是否启用 SSL/TLS。dbint0Redis 数据库索引。ttl_secondsint6048007 天会话 key 的过期时间设为0或负数则禁用过期。key_prefixstradk:session:会话服务创建的所有 Redis key 的前缀。Redis key 结构与状态作用域README 中的核心设计Key 模式数据说明{key_prefix}{app_name}:{user_id}:{session_id}JSONSession会话本体session ID、state、events 列表与最后更新时间按ttl_seconds过期。{key_prefix}user_state:{app_name}:{user_id}JSONdictuser:前缀的用户级状态跨会话共享按ttl_seconds过期。{key_prefix}app_state:{app_name}JSONdictapp:前缀的应用级状态跨用户、跨会话共享按ttl_seconds过期。状态同步规则事件追加user:key增量时同步到用户级状态 key追加app:key时同步到应用级状态 key创建会话或更新事件时三个作用域的状态会合并进会话状态。直接以服务方式使用绕过 Runner 单独管理会话from google.adk.integrations.redis import RedisSessionService from google.adk.sessions.base_session_service import GetSessionConfig session_service RedisSessionService() # 创建会话state 中混合了 user: 作用域与普通作用域键 session await session_service.create_session( app_namemy_app, user_iduser_123, state{user:theme: dark, topic: weather}, ) # 取最近 10 条事件 retrieved await session_service.get_session( app_namemy_app, user_iduser_123, session_idsession.id, configGetSessionConfig(num_recent_events10), ) # 列出该用户所有会话 response await session_service.list_sessions( app_namemy_app, user_iduser_123, ) # 删除会话 await session_service.delete_session( app_namemy_app, user_iduser_123, session_idsession.id, )从 Agent Registry 集成看高层封装模式并非所有集成都只是挂一个工具integrations/agent_registry/agent_registry.py 展示了一种更高层的封装思路AgentRegistry客户端不仅封装了 REST 调用还提供把注册资源转换为可直接使用的 ADK 组件的方法get_mcp_toolset(mcp_server_name, ...)根据注册的 MCP Server 元数据自动解析连接 URI、自动从 IAM bindings 解析认证方案GcpAuthProviderScheme返回一个配置好的McpToolsetget_remote_a2a_agent(agent_name, ...)把注册的 A2A Agent 解析为RemoteA2aAgent优先使用注册卡card否则依据 URI/协议绑定手工构造 agent cardlist_agents/search_agents/list_mcp_servers/search_mcp_servers/list_endpoints等资源管理方法。值得注意的实现细节AgentRegistrySingleMcpToolset同文件 agent_registry.py在McpToolset.get_tools()返回的每个工具上注入GCP_MCP_SERVER_DESTINATION_ID这一custom_metadata键用于在google.adk.telemetry.tracing的execute_toolspan 中标记 MCP 目标——这体现了集成不仅能调用外部服务还能与 ADK 的遥测体系深度协作。该集成同样遵循懒加载规范未安装a2a-sdk时会抛出包含pip install google-adk[a2a]的明确错误。同时它还展示了 mTLS 支持通过GOOGLE_API_USE_MTLS_ENDPOINTauto/always/never与GOOGLE_API_USE_CLIENT_CERTIFICATE环境变量决定是否走agentregistry.mtls.googleapis.com端点。从使用集成到编写集成落地检查清单综合原文档与仓库实践无论使用还是贡献集成都可以用下面的清单快速核对归属代码是否在连接外部服务或依赖第三方库若是放入src/google/adk/integrations/name/而不是核心包自包含是否所有文件都收敛在integrations/name/一个目录内extras 一致pyproject.toml中是否定义了与目录同名的optional-dependencies.name用户能否用pip install google-adk[name]安装懒加载模块顶部是否用try/except ImportError包裹第三方 import并在 except 分支抛出带安装命令的ImportError ... from e文档是否提供独立的 README覆盖安装命令、外部服务配置步骤、配置参数与可运行示例回归测试是否补充了对应单元测试可参考 tests/unittests/integrations/ 下按集成分组的测试组织方式总结ADK 的 Integrations 目录是官方为可扩展性预留的标准化插槽它以自包含子包 可选 extras 依赖 懒加载友好报错 独立文档四条规则在核心轻量与生态丰富之间取得了平衡。对使用者而言pip install google-adk[slack]、google-adk[redis]这类命令就是接入能力的入口对贡献者而言integrations/name/目录加上一份 README 即是新集成的完整交付形态。本文所引用的 integrations/README.md、pyproject.toml 以及 Slack、Redis、Agent Registry 三个子包源码共同构成了理解 ADK 集成机制的最小但完整的证据集。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Google ADK（adk-python）Integrations 集成架构指南：可选依赖、懒加载与子包贡献规范
Google ADKadk-pythonIntegrations 集成架构指南可选依赖、懒加载与子包贡献规范【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python本篇技术指南围绕 src/google/adk/integrations/README.md 展开系统讲解 ADK 中集成Integrations目录的定位、设计原则与扩展方式什么代码应该放进integrations/、如何用可选依赖extras保持核心框架轻量、如何通过懒加载给出友好的错误提示以及如何为外部服务Agent Registry、BigQuery、Slack、Redis 等编写自包含的集成子包。读完本文你将掌握在 adk-python 中新增或使用一个集成模块的完整路径并能在源码层面理解其背后的依赖管理与加载机制。Integrations 目录的定位可扩展的插槽式架构ADKAgent Development Kit采用 code-first 的方式构建、评估与部署 AI Agent。随着生态的扩展Agent 往往需要连接外部工具与服务Agent Registry、BigQuery、ApiHub、Slack、Redis……。如果把这些第三方依赖直接打进核心包会让轻量的核心变得臃肿也会给只使用基础能力的用户带来不必要的安装负担。为此adk-python 在 src/google/adk/integrations/ 下划出了一块专门的集成区所有与外部系统对接的模块都应放入该目录的子包中。这一集中化管理带来两个直接好处可发现性开发者可以在一处浏览、查找、复用所有官方集成可贡献性第三方集成有明确、统一的落位与规范社区贡献者更容易参与。从源码结构看当前仓库的integrations/下已经存在 21 个集成子包覆盖 Google Cloud 服务与第三方生态集成子包主要职责agent_identity基于 Google Cloud 的身份凭证与 AuthProvider 方案agent_registry对接 Google Cloud Agent Registry注册/发现 Agent 与 MCP Serverapi_registry对接 API Registry管理 API 元数据bigqueryBigQuery 查询、元数据、搜索与数据洞察工具集cloud_runCloud Run 部署相关能力crewai与 CrewAI 工具生态的互操作daytona/e2b远程沙箱环境DaytonaEnvironment / E2BEnvironmenteventarcEventarc 事件发布与消息工具firestore/gcs/redis持久化存储Firestore、GCS、Redis 会话服务langchain与 LangChain 工具/结构的互操作livekitLiveKit 实时音视频媒体接入model_armorGoogle Cloud Model Armor 安全防护集成ociOracle Cloud Infrastructure 生成式 AIOCIGenAILlmparameter_manager/secret_managerGCP 参数与密钥管理skill_registryGCP Skill RegistryslackSlackRunner将 Agent 部署到 SlackSocket Modevmaas漏洞管理相关集成以上清单依据 src/google/adk/integrations/ 目录实测列出可作为什么代码属于这里的具体参照。什么属于 Integrations 目录原文档给出了两条判断标准实践中可进一步细化连接外部服务的代码凡是把 ADK 与其它服务、API 或工具连接起来的模块例如 agent_registry/agent_registry.py 中直接对https://agentregistry.googleapis.com/v1发起 REST 请求的AgentRegistry客户端都天然属于此目录。依赖第三方库的模块模块若依赖未包含在 ADK 核心依赖中的第三方库例如 Slack 集成依赖slack-bolt、Redis 集成依赖redis、Agent Registry 依赖a2a-sdk也必须放在这里而不能进入核心包。反过来与外部系统无关的通用能力如 Agent 核心逻辑、Runner、会话服务基类、事件模型等应留在src/google/adk/下对应的核心子包中如agents/、runners.py、sessions/不要把通用代码放进integrations/。贡献指南详解五个必须遵守的规范原文档给出的贡献指南是集成开发的核心约束以下结合仓库源码逐条展开。1. 自包含包每个集成一个独立子目录每个集成应独立存在于自己的子目录中例如integrations/my_service/。这样做的目的是保证集成的边界清晰它可以独立安装、独立测试、独立演进不会与其它集成产生隐式耦合。仓库中的 integrations/slack/、integrations/redis/、integrations/bigquery/ 等都是这一模式的实例每个目录内部都有自己的__init__.py与实现文件且大多附带独立的 README如 integrations/slack/README.md、integrations/redis/README.md。2. 内部结构自由不强制遵循核心框架的组织模式集成子包内部可以自由选择自己的代码结构与设计模式无需严格照搬核心 ADK 框架的组织方式。例如integrations/redis/ 内部采用_config.py_redis_session_service.py的下划线私有模块命名用 Pydantic 配置类承载连接参数integrations/agent_registry/ 则用单个agent_registry.py文件承载一个功能完整的高层客户端类integrations/bigquery/ 拆分为client.py、config.py、query_tool.py、metadata_tool.py、search_tool.py等多个工具文件。可见只要保持子包自包含内部是采用扁平单文件、工具拆分、还是配置与实现分离完全由集成作者根据服务复杂度自行决定。3. 依赖可选化extras 是核心原则为了保持 ADK 核心轻量集成所需依赖必须是可选的并通过pyproject.toml中的optional-dependencies即 pip 的 extras定义。extra 的名称应与集成目录名一致用户通过pip install google-adk[my_service]安装。查看仓库根目录的 pyproject.toml可以看到大量与集成目录一一对应的 extras 定义例如optional-dependencies.slackslack-bolt1.22与aiohttp!3.14.2Socket Mode 适配器依赖 aiohttpoptional-dependencies.redisredis4.2注释说明 4.2 是redis.asyncio落地的版本optional-dependencies.a2aa2a-sdk[http-server]0.3.4,2Agent Registry 与远程 A2A Agent 需要optional-dependencies.livekitlivekit、livekit-api与pillow后者用于对入站视频帧做 JPEG 编码optional-dependencies.ocioci2.126optional-dependencies.bigquery-analyticsgoogle-cloud-bigquery、google-cloud-storage与pyarrow注释说明 pyarrow 体积约占该 extra 安装体积的三分之一因此单独拆分optional-dependencies.gcp、mcp、tools、extensions等聚合类 extra。此外optional-dependencies.all是解锁所有运行时特性的集合pyproject.toml中明确排除了 benchmark、community、dev、docs、test 这类服务于构建/测试/文档自身的 extra。需要一次装齐所有集成能力时可以使用pip install google-adk[all]注意all包含crewai[tools]这类带 Python 版本条件仅 3.11~3.12的依赖实际安装时 pip 会按解释器版本自动过滤。4. 懒加载捕获 ModuleNotFoundError 并给出可操作的错误提示集成代码必须实现懒加载。如果用户未安装对应 extras 就使用该集成应当捕获ModuleNotFoundError并抛出带有正确安装命令的描述性错误。这一规范在 integrations/slack/slack_runner.py 中有教科书级的实现try: from slack_bolt.adapter.socket_mode.aiohttp import AsyncSocketModeHandler from slack_bolt.app.async_app import AsyncApp except ImportError as e: raise ImportError( slack_bolt is not installed. Please install it with pip install google-adk[slack]. ) from e同样的模式也出现在 integrations/agent_registry/agent_registry.py 中其错误信息为raise ImportError( AgentRegistry requires the a2a-sdk package. Please install it using pip install google-adk[a2a]. ) from e这里有两个值得借鉴的细节使用from e保留原始异常链raise ... from e方便调试时追溯根因错误信息直接给出精确的安装命令pip install google-adk[extra]把用户引导到正确的操作上而不是抛出一个模糊的ModuleNotFoundError: No module named slack_bolt。这种延迟 import 友好报错的组合让核心包可以安全地不依赖任何第三方库同时保证用户在误用时第一时间得到解决方案。5. 文档每个集成都要有清晰的 setup / configuration / usage 说明每个集成都应提供清晰文档包含安装、配置与使用示例。仓库中的集成子包大多遵循这一要求其中integrations/slack/README.md 覆盖了前置安装、Slack App 的 Socket Mode/权限/事件订阅配置步骤以及一段可运行的SlackRunner接入代码integrations/redis/README.md 则提供了配置参数表、三种连接方式示例URI、独立连接参数、预配置客户端、Redis key 结构说明与直接调用RedisSessionService的完整代码。写作文档时建议沿用这一结构先讲装什么extras 安装命令再讲外部服务怎么配如 Slack App 权限、GCP IAM最后给最小可用示例。实战一把 Agent 部署到 Slack以 SlackRunner 为例作为使用一个集成的完整示例integrations/slack/README.md 展示了如何把 ADK Agent 通过 Socket Mode 部署到 Slack。整体分四步。第一步安装带 Slack 支持的 ADKpip install google-adk[slack]第二步在 Slack API Dashboard 配置 App打开Socket Mode启用后生成App-Level Token以xapp-开头并确保其具有connections:write权限在OAuth Permissions中添加 Bot Token Scopesapp_mentions:read接收 提及、chat:write发送消息、im:history响应私信按需添加groups:history私密频道与channels:history公开频道在Event Subscriptions中启用事件订阅添加 bot 事件app_mention与message.im将 App 安装到工作区获得Bot User OAuth Token以xoxb-开头。第三步初始化并启动 SlackRunnerimport asyncio import os from google.adk.runners import Runner from google.adk.integrations.slack import SlackRunner from slack_bolt.app.async_app import AsyncApp async def main(): # 1. 初始化 ADK Runner传入你的 agent # runner Runner(agentmy_agent, session_servicemy_session_service) # 2. 用 Bot Token 初始化 Slack AsyncApp slack_app AsyncApp(tokenos.environ[SLACK_BOT_TOKEN]) # 3. 初始化 SlackRunner slack_runner SlackRunner(runnerrunner, slack_appslack_app) # 4. 用 App Token 以 Socket Mode 启动 await slack_runner.start(app_tokenos.environ[SLACK_APP_TOKEN]) if __name__ __main__: asyncio.run(main())第四步理解内部的会话与消息处理机制从 integrations/slack/slack_runner.py 的源码可以看到几个关键设计防循环message事件处理器会跳过带bot_id/bot_profile的消息避免 Agent 与自己对话造成死循环触发条件仅当channel_type im私信或消息处于线程中thread_ts存在时才交由_handle_message处理与 README 中订阅app_mention与message.im的配置相呼应会话 ID 规则与 README 的 Session Management 小节一致私信直接以channel_id作为会话 ID线程以f{channel_id}-{thread_ts}作为会话 ID维持线程上下文App 提及且不在线程中以消息时间戳ts作为thread_ts从而开启一个新线程会话流式体验先发送_Thinking..._占位消息随后在runner.run_async(...)的流式事件中用chat_update把占位消息原地替换为 Agent 输出thinking_ts置空后再用say发后续内容结束后若没有文本输出则chat_delete删除占位消息错误兜底run_async抛出异常时把Sorry, I encountered an error: ...写入占位消息或直接回复同时logger.exception记录堆栈。实战二用 Redis 做持久化会话以 RedisSessionService 为例另一个典型的配置项丰富的集成是 Redis 会话服务其完整文档见 integrations/redis/README.md。它实现了BaseSessionService为 Agent 提供基于 Redis 的持久化会话存储。安装pip install google-adk redis最小接入from google.adk.agents import Agent from google.adk.integrations.redis import RedisSessionService from google.adk.integrations.redis import RedisSessionServiceConfig from google.adk.runners import Runner config RedisSessionServiceConfig( uriredis://localhost:6379/0, ttl_seconds86400 * 7, # 7 天 ) session_service RedisSessionService(configconfig) agent Agent( nameassistant, instructionsYou are a helpful AI assistant., ) runner Runner( app_namemy_app, agentagent, session_servicesession_service, )配置参数表来自 README字段默认值可直接照用字段类型默认值说明uriOptional[str]NoneRedis 连接 URI如redis://[:password]host:port/dbSSL 用rediss://。设置后优先于独立连接字段。hostOptional[str]localhostRedis 主机名。portOptional[int]6379Redis 端口。passwordOptional[str]NoneRedis 认证密码。sslboolFalse是否启用 SSL/TLS。dbint0Redis 数据库索引。ttl_secondsint6048007 天会话 key 的过期时间设为0或负数则禁用过期。key_prefixstradk:session:会话服务创建的所有 Redis key 的前缀。Redis key 结构与状态作用域README 中的核心设计Key 模式数据说明{key_prefix}{app_name}:{user_id}:{session_id}JSONSession会话本体session ID、state、events 列表与最后更新时间按ttl_seconds过期。{key_prefix}user_state:{app_name}:{user_id}JSONdictuser:前缀的用户级状态跨会话共享按ttl_seconds过期。{key_prefix}app_state:{app_name}JSONdictapp:前缀的应用级状态跨用户、跨会话共享按ttl_seconds过期。状态同步规则事件追加user:key增量时同步到用户级状态 key追加app:key时同步到应用级状态 key创建会话或更新事件时三个作用域的状态会合并进会话状态。直接以服务方式使用绕过 Runner 单独管理会话from google.adk.integrations.redis import RedisSessionService from google.adk.sessions.base_session_service import GetSessionConfig session_service RedisSessionService() # 创建会话state 中混合了 user: 作用域与普通作用域键 session await session_service.create_session( app_namemy_app, user_iduser_123, state{user:theme: dark, topic: weather}, ) # 取最近 10 条事件 retrieved await session_service.get_session( app_namemy_app, user_iduser_123, session_idsession.id, configGetSessionConfig(num_recent_events10), ) # 列出该用户所有会话 response await session_service.list_sessions( app_namemy_app, user_iduser_123, ) # 删除会话 await session_service.delete_session( app_namemy_app, user_iduser_123, session_idsession.id, )从 Agent Registry 集成看高层封装模式并非所有集成都只是挂一个工具integrations/agent_registry/agent_registry.py 展示了一种更高层的封装思路AgentRegistry客户端不仅封装了 REST 调用还提供把注册资源转换为可直接使用的 ADK 组件的方法get_mcp_toolset(mcp_server_name, ...)根据注册的 MCP Server 元数据自动解析连接 URI、自动从 IAM bindings 解析认证方案GcpAuthProviderScheme返回一个配置好的McpToolsetget_remote_a2a_agent(agent_name, ...)把注册的 A2A Agent 解析为RemoteA2aAgent优先使用注册卡card否则依据 URI/协议绑定手工构造 agent cardlist_agents/search_agents/list_mcp_servers/search_mcp_servers/list_endpoints等资源管理方法。值得注意的实现细节AgentRegistrySingleMcpToolset同文件 agent_registry.py在McpToolset.get_tools()返回的每个工具上注入GCP_MCP_SERVER_DESTINATION_ID这一custom_metadata键用于在google.adk.telemetry.tracing的execute_toolspan 中标记 MCP 目标——这体现了集成不仅能调用外部服务还能与 ADK 的遥测体系深度协作。该集成同样遵循懒加载规范未安装a2a-sdk时会抛出包含pip install google-adk[a2a]的明确错误。同时它还展示了 mTLS 支持通过GOOGLE_API_USE_MTLS_ENDPOINTauto/always/never与GOOGLE_API_USE_CLIENT_CERTIFICATE环境变量决定是否走agentregistry.mtls.googleapis.com端点。从使用集成到编写集成落地检查清单综合原文档与仓库实践无论使用还是贡献集成都可以用下面的清单快速核对归属代码是否在连接外部服务或依赖第三方库若是放入src/google/adk/integrations/name/而不是核心包自包含是否所有文件都收敛在integrations/name/一个目录内extras 一致pyproject.toml中是否定义了与目录同名的optional-dependencies.name用户能否用pip install google-adk[name]安装懒加载模块顶部是否用try/except ImportError包裹第三方 import并在 except 分支抛出带安装命令的ImportError ... from e文档是否提供独立的 README覆盖安装命令、外部服务配置步骤、配置参数与可运行示例回归测试是否补充了对应单元测试可参考 tests/unittests/integrations/ 下按集成分组的测试组织方式总结ADK 的 Integrations 目录是官方为可扩展性预留的标准化插槽它以自包含子包 可选 extras 依赖 懒加载友好报错 独立文档四条规则在核心轻量与生态丰富之间取得了平衡。对使用者而言pip install google-adk[slack]、google-adk[redis]这类命令就是接入能力的入口对贡献者而言integrations/name/目录加上一份 README 即是新集成的完整交付形态。本文所引用的 integrations/README.md、pyproject.toml 以及 Slack、Redis、Agent Registry 三个子包源码共同构成了理解 ADK 集成机制的最小但完整的证据集。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考