用 A2A 协议打通远程智能体:ADK 多智能体协作实战指南

用 A2A 协议打通远程智能体:ADK 多智能体协作实战指南

【免费下载链接】adk-docsAn open-source, code-first toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-docs

Agent Development Kit(ADK)通过 A2A(Agent2Agent)协议,让你把一个现成的智能体暴露为网络服务,再让另一个智能体像调用本地子智能体一样调用它。跨进程、跨语言、跨团队的智能体协作,从此不需要自己拼通信细节。这篇指南先回答"该不该用 A2A",再带你看懂暴露、消费与联调的完整链路。

先想清楚:子智能体协作,A2A 不是唯一选项

ADK 里让多个智能体协作,其实有两条路:

• 本地子智能体:运行在主智能体同一个进程里,本质上是代码组织手段。通信发生在内存中,没有网络开销,速度最快。
• A2A 远程智能体:作为独立服务部署,通过网络通信,A2A 协议就是这层通信的标准。

怎么选?对照下面这张表基本就有答案:

建议优先选本地子智能体的情况:把单个智能体内复杂任务拆成小模块、高频低延迟的内部操作、需要直接读主智能体内部状态的逻辑。这类场景套上 A2A 反而是负担——网络开销和序列化会拖慢本该最快的路径。

建议选 A2A 的情况:

• 目标智能体是独立服务,比如外部金融数据商通过 A2A 兼容的智能体提供实时行情;
• 智能体由不同团队或组织维护,你无权改它内部代码;
• 需要打通不同语言或不同框架写的智能体(核心业务在 Python,遗留组件在 Java);
• 你构建的是平台,要求贡献者之间遵守严格、可校验的接口契约。

A2A 在 ADK 中的工作方式:一个服务端,一个客户端

抛开术语,A2A 系统在 ADK 里就是两个组件的配合:

1. 暴露端(A2AServer):把你的 ADK 智能体包一层,变成对网络公开的服务,其他智能体可以发送请求。类比一下,就是给你的智能体配了一台 Web 服务器。
2. 消费端(RemoteA2aAgent):客户端代理,知道如何找到并对话那台 A2AServer。网络请求、身份验证、数据格式转换这些脏活都在它背后完成。

连线建立后,对开发者来说,调用远程智能体和调用本地工具几乎没有体感差异——ADK 把网络层整个抽象掉了。

暴露智能体:to_a2a() 与 adk api_server --a2a 怎么选

ADK 提供两条暴露路线,各有取舍。

路线一:to_a2a() 包装,自动生成智能体卡片

适合"我就想把现有智能体变成 A2A 服务"的场景。一行包装,ADK 会从智能体代码中提取技能、能力和元数据,在内存里自动生成智能体卡片:

from google.adk.a2a.utils.agent_to_a2a import to_a2a # 把现有智能体转成 A2A 应用,端口要与实际监听端口一致 a2a_app = to_a2a(root_agent, port=8001)

然后用uvicorn起服务:

uvicorn contributing.samples.a2a.a2a_root.remote_a2a.hello_world.agent:a2a_app --host localhost --port 8001

起好后访问http://localhost:8001/.well-known/agent-card.json,能看到自动生成的卡片内容,说明服务已就绪。两个容易踩的坑:

• port参数只是写进卡片里的宣告值,to_a2a()本身不监听端口,必须和uvicorn --port一致,否则卡片指向一个不可达的地址;
• 也可以传agent_card参数覆盖自动生成的卡片,值可以是AgentCard对象或 JSON 文件路径。

路线二:adk api_server --a2a 托管,配合 adk web 调试

这条路线要求你自己写好智能体卡片(文件名必须精确为agent.json),但换来调试便利:可以直接和adk web联动,而且指向一个父文件夹时,其中所有带卡片的智能体会被同一台服务器批量暴露:

# 在 8001 端口暴露 check_prime_agent adk api_server --a2a --port 8001 contributing/samples/a2a/a2a_basic/remote_a2a

⚠️ 注意:adk api_server --a2a只暴露文件夹中含有agent.json的智能体,漏写卡片文件是"服务起了但没人能看到"的最常见原因。

两条路线的取舍可以这样记:

消费远程智能体:RemoteA2aAgent 的最小配置

消费端只有一个入口:在根智能体里声明一个RemoteA2aAgent,把它挂进sub_agents即可。name和agent_card是必填项,agent_card可以是卡片 URL、本地卡片文件路径或AgentCard对象:

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent prime_agent = RemoteA2aAgent( name="prime_agent", description="检查数字是否为素数的智能体", # 远程智能体卡片地址,指向暴露端提供的 well-known 端点 agent_card="http://localhost:8001/a2a/check_prime_agent/.well-known/agent-card.json", ) root_agent = Agent( model="gemini-flash-latest", name="root_agent", instruction="掷骰子任务交给 roll_agent,素数检查交给 prime_agent", sub_agents=[roll_agent, prime_agent], # roll_agent 为本地子智能体 )

💡RemoteA2aAgent的use_legacy参数默认是True,走的是旧版集成路径;设为False会启用新的 ADK-A2A 集成,由客户端向远端发送 A2A extension。想体验新路径时记得显式设置。

三步联调:本地 roll_agent + 远程 prime_agent

用官方样例完整跑一遍"本地 + 远程"组合:

第一步,安装依赖并获取代码:

pip install google-adk[a2a] git clone https://gitcode.com/GitHub_Trending/ad/adk-docs

第二步,启动远程素数智能体。按上文路线二执行adk api_server --a2a --port 8001 ...(或路线一的uvicorn命令)。为什么固定用 8001?因为消费端adk web默认占用 8000 端口,同一台机器上本地联调时两者必须错开。

第三步,启动消费端开发界面:

adk web contributing/samples/a2a/

打开http://localhost:8000,选择a2a_root智能体开始对话。可以分别验证三种链路:

• "Roll a 6-sided die" → 走本地roll_agent,不经过网络;
• "Is 7 a prime number?" → 走远程prime_agent,经 A2A 协议;
• "Roll a 10-sided die and check if it's prime" → 先本地掷骰,再把结果递给远端,验证组合调用。

能力边界:实验性状态、协议能力与调优开关

最后交代几个影响生产决策的事实:

• 状态:A2A 集成目前处于Experimental阶段,支持 Python、Go、Java;
• 内置能力:ADK 的 A2A 集成支持三类跨智能体传递——保留模型推理链(reasoning)、跟踪长耗时工具调用避免超时、在智能体间传输文件产物(artifacts);
• SDK 兼容:同时兼容a2a-sdk0.3.x 与 1.x,安装版本会自动探测,无需改代码;但 0.3.x 是兼容模式,新集成建议直接面向 1.x;
• 深度定制:暴露端可以通过A2aAgentExecutorConfig替换数据转换器、注入before_agent/after_event/after_agent拦截器;消费端可通过A2aRemoteAgentConfig自定义消息转换与请求拦截;还可用force_new_version=True强制服务端启用新版 executor;
• 降噪:已知晓实验性特性、只想看干净日志时,设置环境变量ADK_SUPPRESS_A2A_EXPERIMENTAL_FEATURE_WARNINGS=true即可屏蔽相关警告。

下一步

暴露和消费的最小闭环跑通后,可以沿着官方文档继续深入:

• docs/a2a/quickstart-exposing.md:暴露端完整教程,含生命周期管理与自定义拦截器;
• docs/a2a/quickstart-consuming.md:消费端完整教程与高级配置;
• docs/a2a/a2a-extension.md:新版 A2A 扩展机制的实现细节。

【免费下载链接】adk-docsAn open-source, code-first toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-docs