Google ADK 入坑实录：原生 MCP+A2A 的多 Agent 系统，我踩了四个坑

凌晨两点，我的三个 Agent 在终端里吵起来了。

一个负责查 GitHub Issue，一个负责读文档，还有一个负责生成测试用例。本来指望它们分工合作，结果 Leader Agent 不知道该把任务派给谁——三个子 Agent 的描述太模糊，LLM 路由直接懵了。

搞了一晚上才发现，问题不在模型，而在框架。我用的那个框架没有原生的多 Agent 层级调度，routing 全靠手写 if-else，改一个 Agent 的职责就要动一堆胶水代码。

后来换到 Google ADK（Agent Development Kit），层级调度、MCP 工具集成、A2A 跨框架通信全是开箱即用——三个小时重写完，跑通了。这篇文章就是这次迁移的完整记录：从选型思路到踩坑过程，再到跟 LangGraph、CrewAI 的对比。

摘要：本文解决多 Agent 系统开发中"框架选型混乱、工具集成痛苦、跨框架通信困难"三个核心问题。以 Google ADK 为实操对象，从零搭建一个带层级调度的多 Agent 系统，集成 MCP 工具和 A2A 协议。读完你能获得：一套可跑的代码、一份框架对比表、以及我踩过的所有坑。

1. 背景：2026 年的 Agent 框架乱战

先说现状。2026 年 Q1，三家大厂在八周内各发了一套 Agent SDK：

加上 LangGraph、CrewAI、Pydantic AI、smolagents 这些老牌和新兴选手，Python Agent 框架已经超过 12 个。

说白了，选框架比写 Agent 还累。

我的场景是这样的：需要一个coordinator分发任务给多个 specialist agent，每个 specialist 可能调用不同的外部工具（数据库、搜索引擎、GitHub API），而且这些工具最好能通过 MCP 协议即插即用。

试了 CrewAI——角色扮演很酷，但确定性的 pipeline 编排很弱。试了 LangGraph——图结构灵活到爆炸，但 MCP 集成得自己写 adapter。最后看到 Google ADK 的设计文档，发现它把 MCP 和 A2A 作为框架的一等公民，不是插件。

就它了。

2. 技术原理：ADK 的架构为什么不一样

ADK 的核心设计有三个原则，理解了这三个，后面写代码就不会踩坑。

原则一：Agent 是可组合的单元

每个 Agent 都是一个独立单元，可以单独运行，也可以嵌套进层级结构里。父 Agent 看子 Agent 的description字段来决定路由。

graphTDA[CoordinatorAgent]-->B[ResearchAgent]A-->C[CodeReviewAgent]A-->D[GreeterAgent]B-->E[GitHubSearchTool]B-->F[WebSearchTool]C-->G[MCP:GitHubAPI]C-->H[MCP:CodeAnalysis]

这里有两种调度模式：

LLM 驱动路由：父 Agent 是LlmAgent，读子 Agent 的 description，LLM 自行判断把任务给谁。适合开放式对话场景。

确定性工作流：不经过 LLM 路由，用三种 Workflow Agent：
-SequentialAgent——子 Agent 按顺序执行
-ParallelAgent——子 Agent 并发执行，结果汇总
-LoopAgent——循环执行直到满足退出条件

说个坑：一开始我把所有子 Agent 都挂在 LlmAgent 下面，以为 LLM 路由万能。结果当一个子 Agent 的 description 写得不够具体时，LLM 经常把任务派错人。后来改成确定性 SequentialAgent，问题消失。

原则二：MCP 和 A2A 是框架原生能力

这是 ADK 跟其他框架最大的区别。

|MCP（Model Context Protocol）解决的是 Agent 和工具之间的通信。标准化的协议意味着：只要工具实现了 MCP Server，任何 ADK Agent 都能直接调用。目前生态里已经有 {2000+ || 来源:paperclipped.de Google ADK 2026 指南} 个 MCP Server——Slack、PostgreSQL、Jira、Google Drive……直接拿来用。 |

A2A（Agent-to-Agent）解决的是 Agent 和 Agent 之间的通信。跨框架的那种。ADK 的 Agent 可以调用一个 LangGraph 写的 Agent，也可以被 CrewAI 的 Agent 调用——不需要写一行集成代码。

graphLR|A[ADKAgent]-->|MCP|B[SlackMCPServer]||A-->|MCP|C[PostgreSQLMCPServer]||A-->|A2A|D[LangGraphAgent]||A-->|A2A|E[CrewAIAgent]|

对比一下：在 LangGraph 里接 MCP，得装langchain-mcp-adapters；在 CrewAI 里接 MCP，社区有插件但不是官方维护。ADK 直接内置。

原则三：代码优先，不是配置优先

ADK 的所有 Agent 定义、工具绑定、编排逻辑都是纯 Python 代码。不用写 YAML，不用拖拽流程图。

好处是：版本控制、单元测试、类型检查这些工程实践都能直接套上。

3. 环境准备

我用的环境：

• Python 3.12（ADK 官方推荐 3.9+，但 3.12 的类型提示最完善）
• Google ADK v1.0.0
• 操作系统：Ubuntu 22.04（WSL2 也可以）

# 创建虚拟环境python3.12-mvenvadk-envsourceadk-env/bin/activate# 安装 ADKpipinstallgoogle-adk==1.0.0# 验证安装adk--version# 输出: adk 1.0.0

然后配置 API Key。ADK 优先用 Gemini，但也通过 LiteLLM 支持 Claude、GPT-4 等。

# Gemini（推荐，免费额度够开发用）exportGOOGLE_API_KEY="your-api-key-here"# 如果想用 Claude，需要额外配置 LiteLLMexportANTHROPIC_API_KEY="your-anthropic-key"

对了，如果你用的是 Vertex AI 而不是直接调 Gemini API，认证方式不一样——要走gcloud auth application-default login。别搞混了，我第一次就是搞混了认证方式，报了一堆 401 错误，折腾了半小时。

4. 实战：搭一个代码审查多 Agent 系统

目标：搭一个包含三个 Agent 的系统——Coordinator 负责分发，Researcher 负责查资料，Reviewer 负责代码审查。

4.1 最简单的单 Agent

先跑通一个最小的 Agent，确认环境没问题：

# agent.pyfromgoogle.adk.agentsimportLlmAgentagent=LlmAgent(model="gemini-2.0-flash",name="hello_agent",description="A simple greeting agent",instruction="You are a helpful assistant. Respond concisely.",)# 本地运行# adk run agent.py

运行命令：

adkrunagent.py

终端里会出现交互界面，输入问题就能对话。如果报错说找不到 model，检查GOOGLE_API_KEY环境变量。

4.2 加上 MCP 工具

现在给 Researcher Agent 接入 GitHub MCP Server，让它能查 Issue 和 PR：

# research_agent.pyimportasynciofromgoogle.adk.agentsimportLlmAgentfromgoogle.adk.tools.mcpimportMCPToolset,StdioServerParametersasyncdefmain():# 连接 GitHub MCP ServerasyncwithMCPToolset.from_server(connection_params=StdioServerParameters(command="npx",args=["-y","@modelcontextprotocol/server-github"],))astools:researcher=LlmAgent(model="gemini-2.0-flash",name="researcher",description="Searches GitHub issues, PRs, and documentation. ""Use this agent when the user asks about code repositories, ""bugs, or open-source projects.",instruction=("You are a research specialist. ""Always cite the source (issue number, PR link, etc.). ""Be concise and factual."),tools=tools,)print("Researcher agent ready with GitHub MCP tools.")asyncio.run(main())

这里有个坑。第一次运行时npx会下载@modelcontextprotocol/server-github，如果网络不好会卡住。我公司的网络就卡了 5 分钟，还以为代码写错了。

另外，GitHub MCP Server 需要 GitHub Token：

exportGITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"

没设这个 Token，MCP Server 能启动但所有 API 调用都返回 403。

4.3 搭建层级多 Agent 系统

把 Coordinator、Researcher、Reviewer 组装到一起：

# multi_agent.pyimportasynciofromgoogle.adk.agentsimportLlmAgent,SequentialAgentfromgoogle.adk.tools.mcpimportMCPToolset,StdioServerParametersasyncdefbuild_system():# Researcher Agent（带 MCP 工具）asyncwithMCPToolset.from_server(connection_params=StdioServerParameters(command="npx",args=["-y","@modelcontextprotocol/server-github"],))asgithub_tools:researcher=LlmAgent(model="gemini-2.0-flash",name="researcher",description=("Searches GitHub for issues, pull requests, and documentation. ""Returns findings with citations."),instruction="You are a research specialist. Find relevant context.",tools=github_tools,)# Reviewer Agent（纯 LLM，不需要外部工具）reviewer=LlmAgent(model="gemini-2.0-flash",name="reviewer",description=("Analyzes code and provides review comments. ""Focuses on security, performance, and readability."),instruction=("You are a senior code reviewer. ""Identify potential bugs, security issues, and improvements. ""Rate severity: critical / warning / suggestion."),)# Coordinator——LLM 驱动路由coordinator=LlmAgent(model="gemini-2.0-flash",name="coordinator",description="Routes user requests to the appropriate specialist.",instruction=("You are a coordinator. Analyze the user's request and decide ""which specialist to delegate to. ""For code review requests, use the reviewer. ""For research about repositories or issues, use the researcher. ""For general questions, answer directly."),sub_agents=[researcher,reviewer],)print("Multi-agent system ready!")# 实际运行用 adk web 或 adk runasyncio.run(build_system())

跑起来之后，你可以问"帮我查一下 langchain-ai/langchain 最近的 Issue"——Coordinator 会自动把这个任务派给 Researcher，Researcher 通过 MCP 调 GitHub API 拿数据，然后把结果返回。

一个关键细节：sub_agents的顺序不影响 LLM 路由。LLM 是读description来决策的，所以 description 写得越具体越好。我一开始写了个 "Helps with research"——太模糊了，LLM 经常把代码审查的请求也发给它。改成 "Searches GitHub for issues, pull requests, and documentation" 之后，路由准确率从大约 70% 提升到 95% 以上。

5. 效果验证与框架对比

实测数据（同一个"查 Issue + 审代码"任务，在不同框架下实现）：

说个真实的感受：如果你需要的是"三个人各干各的活"，CrewAI 最快上手。但一旦你需要 MCP 即插即用 + 跨框架 Agent 通信 + 确定性 pipeline，ADK 是目前唯一一个原生支持的。

不过话说回来，LangGraph 在状态管理上还是最强的——如果你的 Agent 需要复杂的状态转换（比如审批流、驳回重做），LangGraph 的图结构比 ADK 的层级结构更灵活。

你平时用哪个框架？有在 ADK 上踩过别的坑吗？评论区说说，我整理到后续文章里。

6. 踩坑记录

坑 1：MCP Server 启动超时

症状：MCPToolset.from_server卡住不动，没有报错也没有返回。

原因：npx首次运行需要下载包，网络慢就会超时。ADK 默认的 MCP 连接超时比较短。

解决：提前全局安装 MCP Server，或者设更长的超时：

# 提前安装npminstall-g@modelcontextprotocol/server-github

坑 2：LLM 路由不准

症状：Coordinator 把研究任务派给了 Reviewer，或者反过来。

原因：子 Agent 的description写得太笼统。LLM 路由完全依赖这个字段做判断。

解决：description 写得像 JD（岗位描述）一样具体。包括"擅长什么"和"不擅长什么"。或者干脆用SequentialAgent做确定性编排。

坑 3：Gemini API 限流

症状：并发请求多时返回 429 错误。

解决：加tenacity做指数退避重试：

fromtenacityimportretry,stop_after_attempt,wait_exponential@retry(stop=stop_after_attempt(3),wait=wait_exponential(multiplier=1,min=2,max=10))asyncdefrun_agent(agent,message):returnawaitagent.run(message)

坑 4：A2A 调试困难

症状：跨框架 Agent 调用时，对端 Agent 返回的结果格式跟预期不一致。

原因：A2A 协议目前还在早期阶段，不同框架的 A2A 实现可能有细微差异。

解决：加 logging，打印 A2A 请求和响应的原始 JSON。别靠猜。

7. 总结

Google ADK 的核心价值就三件事：

1. MCP 原生集成——2000+ 工具即插即用，不用写 adapter
2. A2A 跨框架通信——Agent 可以跨框架协作，这在企业场景里太重要了
3. 层级多 Agent 调度——LLM 路由和确定性编排两种模式，覆盖大多数场景

但 ADK 也有短板：社区比 LangGraph 和 CrewAI 年轻，Stack Overflow 上的答案少；精细的状态管理不如 LangGraph 灵活；文档虽然完整但有些地方缺少踩坑指南（所以我在写这篇）。

框架选型没有银弹。我的建议是：先明确你的核心需求——是工具集成（选 ADK），是状态控制（选 LangGraph），还是快速原型（选 CrewAI）？从需求出发，别从框架出发。

| ADK v1.0 已经可以上生产了——{Renault Group、Box、Revionics || 来源:paperclipped.de Google ADK 指南} 都在用。但如果你是第一次接触 Agent 开发，建议先从 CrewAI 入门，搞清楚 Agent、Tool、Memory 这些基本概念后再迁移到 ADK。 |

你有在生产环境跑过 Agent 系统吗？用的什么框架？遇到过哪些"文档里没写但实际部署会炸"的坑？评论区聊聊。