ADK 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-docsAgent Development KitADK是用于构建、评估和部署 AI 智能体的开源代码优先工具包其 A2AAgent2Agent协议让部署在不同机器、用不同语言编写的智能体也能像调用本地函数一样互相协作。下面把 A2A 在 ADK 中的核心原理、适用边界和上手方法一次讲透。核心概念与定位A2A 协议在 ADK 智能体体系中的位置它是什么A2A 协议是智能体间通信的标准协议定义了如何发现并调用以独立服务形式运行的另一个智能体。在 ADK 中暴露端用to_a2a()或adk api_server --a2a把智能体变成 A2AServer消费端用RemoteA2aAgent把远端智能体包装成普通子智能体。它解决什么问题单一智能体往往覆盖不了所有需求。当所需能力位于独立服务中、由其他团队维护、或用不同语言Python/Go/Java编写时你需要一个统一的、带正式契约的通信层而不是各团队私定一套 HTTP 接口。它处于什么位置A2A 是 ADK 多智能体编排的网络边界能力。下图是 ADK 的组件全景本地子智能体、工作流智能体都留在进程内只有跨越进程和机器边界时才轮到 A2A 登场。本地子智能体与 A2A 远程智能体的核心差异可以浓缩成三个维度维度本地子智能体A2A 远程智能体部署形态同一应用进程独立服务可跨机器通信方式内存直接调用无网络开销走网络A2A 协议序列化维护边界同一代码库、同一团队跨团队、跨语言、跨框架内部机制拆解A2A 协议的完整暴露与消费流程ADK 中的 A2A 工作流可以拆成六步定义智能体用 ADK 的Agent正常编写root_agent可挂载本地子智能体此步骤与 A2A 完全解耦。用to_a2a()暴露一行函数把现有智能体包成 A2A 应用背后自动生成 AgentCard智能体名片描述能力与地址。选择暴露路径条件A要完全掌控服务化过程 →to_a2a()uvicorn托管条件B想配合adk web调试 →adk api_server --a2a含agent.json的目录会被自动暴露名片发现远端智能体在/.well-known/agent-card.json路径提供名片消费方无需读源码即可了解其技能。消费远程智能体RemoteA2aAgent填入名片 URL客户端代理负责网络通信、鉴权与数据转换。透明调用root_agent按指令委派任务请求经网络抵达远端 A2A 服务器开发者视角与调用本地工具无异。选型决策什么时候该用 A2A什么时候别用官方文档对适用条件有明确界定直接引用✅ 适合场景独立服务协作目标智能体是单独的服务跨进程、跨机器部署。多团队共同维护智能体由其他团队管理协议充当正式契约。跨语言集成需要连接 Python、Go、Java 等不同框架的智能体。平台化能力开放把内部专业能力作为 A2A 服务对外输出。⚠️ 不适用场景智能体内部拆解拆分单个智能体的内部模块用本地子智能体。高频低延迟操作高频调用下网络与序列化开销不可接受。共享内存/状态需直接读写主智能体内部状态时。简单辅助函数小而可复用的逻辑一个函数就够了。 动手实操从零跑通第一个 A2A 智能服务准备环境执行pip install google-adk[a2a]安装 A2A 扩展依赖并准备好 Gemini 模型 API Key。ADK 会自动探测已安装的 a2a-sdk 版本0.3.x 与 1.x 均兼容无需手动锁定。核心配置下面的代码定义一个最小智能体并用to_a2a()将其包装为 A2A 应用智能体卡片会在后台自动生成。from google.adk.agents import Agent from google.adk.a2a.utils.agent_to_a2a import to_a2a root_agent Agent( modelgemini-flash-latest, namehello_world_agent, instructionYou can roll dice and check prime numbers., ) # 包装为 A2A 应用port 必须与实际服务端口一致 a2a_app to_a2a(root_agent, port8001)也可以通过agent_card参数传入自己的AgentCard对象或 JSON 文件路径替代自动生成的卡片。运行验证启动 A2A 服务器与开发界面再请求卡片地址确认暴露成功。# 终端1启动 A2A 服务器 uvicorn my_agent.agent:a2a_app --host localhost --port 8001 # 终端2启动开发界面注意端口与 8001 错开 adk web . # 验证自动生成的智能体卡片 curl http://localhost:8001/.well-known/agent-card.json服务器就绪后adk web界面里就能直接调试该智能体左侧面板可在 Trace、Events、State 等视图间切换观察调用的完整过程。实战场景客服智能体与产品目录智能体端到端协作看一个典型业务链路客服智能体support_agent要回答产品咨询但商品数据在另一个团队维护的产品目录智能体catalog_agent手里。调用链路为support_agent →委派→ RemoteA2aAgent → A2A Server → catalog_agent。之前怎么做痛点没有标准接口时客服端只能硬编码目录服务的私有 API目录服务改一次字段客服端就得跟着改若是跨语言服务比如目录是 Java 写的耦合只会更难受。现在怎么做解法目录智能体以 A2A 服务暴露附带描述其能力的agent.json客服智能体用RemoteA2aAgent消费代码只有几行from google.adk.agents import Agent from google.adk.agents.remote_a2a_agent import RemoteA2aAgent catalog_agent RemoteA2aAgent( namecatalog_agent, descriptionHandles product catalog lookups, agent_cardhttp://catalog-svc:8001/.well-known/agent-card.json, ) root_agent Agent( modelgemini-flash-latest, namesupport_agent, sub_agents[catalog_agent], )效果客服智能体只面向 A2A 契约编程不关心目录服务的实现细节。目录智能体可以独立升级、扩容甚至换语言重写客服侧零改动。整个分布式智能体系统的拓扑如下避坑指南与最佳实践端口不一致to_a2a() 的 port 必须与实际服务端口一致否则名片地址不可达。名片文件命名api_server --a2a 只暴露含 agent.json 的目录文件名写错会被跳过。SDK 版本选择新集成面向 a2a-sdk 1.x0.3.x 仅兼容模式。新旧路径切换RemoteA2aAgent 默认 use_legacyTrue新集成需显式置 False。实验特性告警A2A 仍属实验功能可设环境变量 ADK_SUPPRESS_A2A_EXPERIMENTAL_FEATURE_WARNINGStrue 静音。总结与延伸A2A 协议把智能体调用智能体从私定接口的猜谜游戏变成了标准契约to_a2a()暴露、RemoteA2aAgent消费网络层全部被 ADK 隐藏。对跨团队、跨语言的分布式智能体协作它是 ADK 体系里目前最直接的选择而进程内的子智能体拆分依然应该优先用本地子智能体选对工具比堆技术更重要。A2A 协议简介何时用、何时不用Python 暴露智能体快速入门to_a2a 详解Go 语言 A2A 示例代码试着把 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考