用 Google ADK 把智能体接上 MCP 工具并暴露成 A2A 服务（to_a2a 实操）

智能体开发里有两种「连接」：Agent 连工具，靠 MCP（Model Context Protocol）；Agent 连 Agent，靠 A2A（Agent2Agent 协议）。Google 的 Agent Development Kit（ADK）把两者都做成了内置能力：既可以通过 MCP 客户端加载外部工具服务，也可以用 to_a2a() 函数把任何 ADK 智能体变成一个说 A2A 协议的服务器——自动生成智能体名片（agent card）、JSON-RPC 端点与流式支持。本站教程 414 讲过 ADK 的安装上手与调试，本篇聚焦它的「对外连接」能力：接上 MCP 工具，再把智能体暴露成别的 Agent 能调用、人类能验证的 A2A 服务。

实操路径完全按 Google 官方 currency-agent Codelab（2026 年 9 月 30 日更新）走：这是一个接入远程 MCP 汇率工具的货币智能体，从环境准备到 A2A 服务器验证，每一步都有官方仓库代码兜底。读完你将拥有两个可复用的资产：一支带 MCP 工具的 ADK 智能体，和一套把它暴露成 A2A 服务的两行模板。

前置准备：Python 3.12 或更高、uv 包管理器（Codelab 用 uv 管理依赖与运行）、一个 Google AI API Key（Agent 调用 Gemini 模型用）、git。全程在本地终端完成，不需要创建 GCP 项目。

ADK 与 A2A Python SDK 都在快速演进，本篇命令与代码以官方 Codelab 与 adk-python 仓库当前版本为准；类名或导入路径报错时，先查你所装版本的官方文档，不要硬抄旧教程。

Step 1：环境准备：装 google-adk[a2a] 扩展

1 环境准备：装 google-adk[a2a] 扩展

ADK 的 A2A 能力在扩展依赖里，安装时带上 [a2a] extra，再配好模型 Key：

mkdir a2a-lab
cd a2a-lab
python -m venv .venv
source .venv/bin/activate   # Windows 用 .venv\Scripts\activate

pip install "google-adk[a2a]"
export GOOGLE_API_KEY="你的API密钥"   # Windows: set GOOGLE_API_KEY=...

这个 extra 会一并装上 A2A Python SDK——to_a2a() 在幕后用它生成智能体名片和处理 JSON-RPC。装完先验证导入：python -c "import google.adk; print(google.adk.__version__)"，确认版本号后再往下走。

Step 2：定义一支标准 ADK 智能体

2 定义一支标准 ADK 智能体

先写一支最小但完整的 ADK 智能体。官方示例的结构是四要素：model、name、description、instruction——注意 name 与 description 不只是内部标识，它们会被 to_a2a() 自动写进对外的智能体名片：

# research_agent/agent.py
from google.adk import Agent

research_agent = Agent(
    model="gemini-2.0-flash",
    name="research_assistant",
    description="A research assistant that summarizes topics and answers questions.",
    instruction="""You are a research assistant.
When given a topic or question:
1. Provide a clear, well-structured answer
2. Include relevant facts and context
3. Keep responses focused and concise.""",
)

用 adk web 或直接跑一段脚本验证这支智能体能正常应答，再进入下一步。模型名以你账号可用的型号为准，官方示例用的 gemini-2.0-flash 属于效率优先的选择。

instruction 里写清「回答结构、长度上限、模糊时先追问」这类行为契约。这些约束会随名片暴露给调用方，是 A2A 生态里「这个智能体擅长什么」的软文档。

Step 3：接入 MCP 工具：拉官方 Codelab 仓库

3 接入 MCP 工具：拉官方 Codelab 仓库

MCP 工具接入最稳妥的路径是直接用官方 Codelab 的完整实现。Codelab 的 currency agent 在启动时会从远程 MCP Server 加载汇率工具——服务器启动日志里能看到官方脚本打印的「Loading MCP tools from MCP Server...」字样。克隆官方示例仓库：

git clone https://github.com/google/adk-python.git
# Codelab 配套代码与 A2A 官方示例都在仓库内：
# contributing/samples/a2a/ 下有 a2a_root、a2a_basic、
# a2a_human_in_loop 等五组官方维护的 A2A 示例
cd adk-python

currency-agent Codelab 页面（codelabs.developers.google.com/codelabs/currency-agent）内嵌了完整代码与逐步操作。MCP 客户端的连接参数（stdio 还是 HTTP、服务器地址、工具清单）在仓库代码里都有现成写法——照着仓库当前版本抄，不要凭记忆手写连接配置：MCP 连接参数的字段名在协议版本间有过调整。

MCP 工具是真实外部调用：接入的第三方 MCP Server 能拿到你发送的查询内容。接生产前审查服务端来源，工具返回内容一律当数据不当指令（防提示注入），敏感查询走自建 MCP Server。

Step 4：两行暴露 A2A 服务器

4 两行暴露 A2A 服务器

官方 Codelab 原文的暴露代码只有两行。把 to_a2a 套在根智能体上，返回一个 uvicorn 可直接运行的 ASGI 应用：

# currency_agent/agent.py 内（官方 Codelab 原文结构）
from google.adk.a2a.utils.agent_to_a2a import to_a2a
from agent import root_agent

# Make the agent A2A-compatible
a2a_app = to_a2a(root_agent, port=10000)

按 Codelab 原文启动服务器：

uv run uvicorn currency_agent.agent:a2a_app --host localhost --port 10000

启动成功时你会看到官方日志里的三行标志：加载 MCP 工具、创建 ADK 智能体、Uvicorn running on http://localhost:10000。此刻你的智能体已经是一个说 A2A 协议的服务器——名片自动生成、JSON-RPC 的 message/send 与 message/stream 端点就绪。官方文档特别说明：相比手工编写名片的 adk api_server 路线，to_a2a 是最直接的自动化路径。

to_a2a(port=) 与 uvicorn --port 必须一致，名片里记录的服务地址来自这个端口，端口对不上时远程调用方会按名片连到错误位置——这是 A2A 联调最常见的一类故障。

Step 5：验证名片与远程调用

5 验证名片与远程调用

先取名片确认服务活着。to_a2a() 按 A2A 规范把名片挂在众所周知的位置，用 curl 验证：

curl -s http://localhost:10000/.well-known/agent-card.json

# 返回体关键字段（官方示例结构）：
# name / description  <- 来自你 Agent 的 name 与 description
# capabilities        <- streaming 等能力开关
# defaultInputModes / defaultOutputModes
# skills              <- 技能清单（id、name、description）

名片没问题，就用 JSON-RPC 发一次真实任务——官方示例的请求体结构如下：

JSON-RPC 请求里的 id 字段是你自己起的调用编号，返回体会原样带回，用它把请求与响应配对；需要边生成边收更新的场景把 method 换成 message/stream，走 SSE 流式返回。

curl -X POST http://localhost:10000/ -H "Content-Type: application/json" -d '{
  "jsonrpc": "2.0",
  "id": "test-1",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "把 100 美元换算成日元是多少" }]
    }
  }
}'

返回体里带任务 ID 与状态，任务完成后结果在 artifacts 里。官方还提供 A2A Inspector 网页调试工具，可以可视化查看名片、直接对话、并检查来往的 JSON-RPC 原始报文——联调阶段比 curl 顺手得多。

Step 6：跨智能体消费与上生产前检查

6 跨智能体消费与上生产前检查

A2A 的意义在「另一支 Agent 调用你的 Agent」。官方 samples 里 a2a_root 示范了把远程 A2A 智能体直接当 root agent 用，a2a_human_in_loop 示范了人在回路的跨智能体协作——远程侧的智能体类（RemoteA2aAgent）指向名片地址，ADK 负责协议细节。把 Step 4 的服务器跑着，另一支本地智能体按名片连接，就完成了「Agent 调 Agent」的最小闭环。

上生产前的检查清单：名片是公开契约——name、description、skills 会被生态里的调用方索引，写清楚能力边界，也别把内部代号或敏感信息写进去；端点必须加鉴权（认证反代或网关层），裸奔的 A2A 服务等于把模型调用权公开；版本管理上，名片内容变更相当于 API 变更，要有意识地通知调用方。

团队内多智能体协作的落地节奏建议：先在内部网络用 A2A 把几支独立智能体连起来（各自独立迭代、独立部署），验证稳定后再考虑对外提供名片。A2A 的价值在边界清晰，不在一次性把所有逻辑塞进一个大 Agent。

预期效果自查：Step 4 启动日志出现加载 MCP 工具与 Uvicorn 监听两行标志；Step 5 的名片请求返回含 name 与 skills 的 JSON；JSON-RPC 调用返回带任务状态与 artifacts 的结果。三项全过，说明「MCP 进工具、A2A 出服务」的通路已经打通。

常见问题 FAQ

什么时候用 MCP、什么时候用 A2A？给智能体加能力（查数据、调 API、执行动作）用 MCP，接的是工具；把智能体本身作为服务暴露给其他智能体协作用 A2A，接的是「会思考的同行」。两者在 ADK 里可以同时存在：一支智能体既挂 MCP 工具，也被 to_a2a 暴露出去。

名片（agent card）能手工定制吗？可以。官方文档提到另一条 adk api_server 路线需要手工编写名片，适合需要精细控制对外元数据的场景；to_a2a 自动生成的名片取自 Agent 的 name 与 description，改元数据等于改这两个字段。

一定要 GCP 项目才能跑吗？本地跑通不需要——只要 GOOGLE_API_KEY 能调 Gemini。Codelab 后半段的 Cloud Run 部署、Agent Engine 托管属于上生产章节，按需再跟；把本地 A2A 服务放内网供团队其他智能体调用，同样不需要任何云资源。