跳到主要内容
Spring AI Alibaba A2A 分布式智能体通信实战指南 | 极客日志
Java AI java
Spring AI Alibaba A2A 分布式智能体通信实战指南 Spring AI Alibaba A2A 协议实现智能体间分布式通信。通过 Nacos 注册中心自动发现服务,支持负载均衡与健康检查。核心功能包括 AgentCard 元数据管理、同步与异步调用、流式响应处理。提供完整的 Maven 依赖配置、环境搭建及代码示例,涵盖服务提供者与消费者开发流程,解决多智能体协作中的服务寻址与故障恢复问题,助力构建弹性可扩展的 AI 应用架构。
Spring AI Alibaba A2A 分布式智能体通信实战指南
1. A2A 概述
1.1 什么是 A2A
A2A (Agent-to-Agent) 是 Spring AI Alibaba 提供的智能体间通信协议和框架,允许不同的智能体通过网络进行发现、通信和协作。
A2A 主要解决以下核心问题:
服务发现 :智能体如何找到其他智能体?
远程调用 :如何像调用本地智能体一样调用远程智能体?
负载均衡 :如何在多个智能体实例间分配请求?
故障恢复 :如何处理网络故障和服务不可用?
核心理念很简单:让分布式智能体系统的开发像单体应用一样简单。
1.2 为什么需要 A2A
在现代 AI 应用中,单个智能体往往无法解决所有问题。A2A 提供了构建分布式智能体系统的能力。
专业化分工
不同的智能体可以专注于不同的领域。例如,一个路由智能体可以将用户请求分发给技术专家、商业专家或法律专家智能体。每个专家智能体可以使用专门的模型、配置特定的工具、优化特定的提示词,并独立部署和扩展。
资源隔离
不同的智能体服务可以部署在不同的服务器上,使用不同的计算资源,设置不同的 API 配额,实现独立扩容和缩容。
团队协作与复用
大型 AI 应用可以由多个团队并行开发,通过统一的 A2A 协议进行集成。通用智能体(如翻译、计算)可以被多个应用复用,避免重复建设。
1.3 应用场景
企业级智能客服 :路由智能体识别问题类型,分发给订单、技术支持或售后服务智能体。
多专家咨询系统 :协调智能体将投资问题分发给金融、税务、法律和风险专家,最后汇总建议。
智能研究助手 :规划智能体制定计划,分发任务给文献检索、数据收集、分析和撰写智能体。
跨部门协作 :项目管理智能体协调开发、设计、测试、运维和产品部门的智能体共同完成项目需求。
1.4 核心特性
透明的远程调用
调用远程智能体就像调用本地智能体一样简单:
ReactAgent localAgent = ...;
localAgent.invoke("你好" );
A2aRemoteAgent remoteAgent = ...;
remoteAgent.invoke("你好" );
自动服务发现
智能体自动注册和发现,无需手动配置 IP 地址。服务提供者启动时自动注册,消费者通过名称即可发现。
负载均衡与健康检查
自动在多个智能体实例间分配请求,并检测健康状态。不健康的实例会被自动摘除,确保流量只流向可用节点。
版本管理与灰度发布
支持多版本智能体共存,可逐步将流量切换到新版本,降低升级风险。
2. A2A 架构
2.1 整体架构
应用层 :包含各个具体的智能体(Agent A, B, C)。
A2A 框架层 :包含 Server(服务端)和 Client(客户端),负责暴露 REST API 和处理远程调用。
基础设施层 :注册中心(Nacos)提供服务和配置管理,网络传输层处理 HTTP/gRPC/WebSocket 通信。
2.2 核心组件
A2A Server(服务端) 职责包括暴露本地智能体为 REST API、向注册中心注册服务、发送心跳保持在线状态、处理远程调用请求。
A2aServerAutoConfiguration - 自动配置
A2aAgentEndpoint - REST 端点
NacosAgentRegistry - Nacos 注册器
A2A Client(客户端) 职责是从注册中心发现服务、创建远程智能体代理、发起 HTTP 调用、处理响应和异常。
A2aRemoteAgent - 远程智能体代理
AgentCardProvider - 服务发现提供者
NacosAgentDiscovery - Nacos 服务发现
AgentCard(服务元数据) AgentCard 包含智能体的所有元信息,相当于服务的'名片'。
public class AgentCard {
private String name;
private String description;
private String version;
private String endpoint;
private List<String> capabilities;
private Map<String, String> metadata;
}
{
"name" : "customer_service" ,
"description" : "智能客服机器人" ,
"version" : "1.0.0" ,
"endpoint" : "http://192.168.1.10:8081" ,
"capabilities" : [ "tool_calling" , "streaming" , "chinese" ] ,
"metadata" : { "team" : "customer-support" , "owner" : "[email protected] " }
}
AgentCardProvider(服务发现) 提供服务发现接口,实现类包括基于 Nacos 的 NacosAgentCardProvider 和用于测试的 StaticAgentCardProvider。
2.3 工作原理
服务注册流程
Spring Boot 应用启动,加载配置并初始化 Bean。
A2aServerAutoConfiguration 扫描 ReactAgent Bean。
为每个 ReactAgent 创建 REST 端点。
构造 AgentCard。
向 Nacos 注册服务。
启动心跳线程,每 5 秒发送一次心跳。
服务发现流程
创建 A2aRemoteAgent 时,根据名称查询 AgentCard。
NacosAgentCardProvider 从 Nacos 获取服务实例列表。
应用负载均衡策略选择一个健康实例。
构造 AgentCard 并缓存(默认 30 秒)。
远程调用流程
获取 AgentCard(从缓存或 Nacos)。
构造 HTTP 请求(POST /api/a2a/{agentName})。
发送到远程服务。
远程服务查找本地 ReactAgent 并调用。
接收响应并解析。
处理错误(超时重试、切换实例等)。
2.4 通信协议
REST API
端点 :POST /api/a2a/{agentName}
请求格式 :JSON,包含消息列表和配置。
响应格式 :JSON,包含消息列表和元数据。
流式响应 对于流式调用,使用 Server-Sent Events (SSE)。
端点 :POST /api/a2a/{agentName}/stream
响应 :SSE 格式的数据流。
3. 快速开始
3.1 环境准备
JDK 17 或更高版本
Maven 3.6+ 或 Gradle 7+
Nacos 2.0+(用于服务注册与发现)
安装 Nacos docker run -d \
--name nacos \
-e MODE=standalone \
-p 8848:8848 \
-p 9848:9848 \
nacos/nacos-server:latest
3.2 创建服务提供者
创建 Maven 项目 <dependencies >
<dependency >
<groupId > org.springframework.boot</groupId >
<artifactId > spring-boot-starter-web</artifactId >
</dependency >
<dependency >
<groupId > com.alibaba.cloud.ai</groupId >
<artifactId > spring-ai-alibaba-agent-framework</artifactId >
<version > ${spring-ai-alibaba.version}</version >
</dependency >
<dependency >
<groupId > com.alibaba.cloud.ai</groupId >
<artifactId > spring-ai-alibaba-starter-dashscope</artifactId >
<version > ${spring-ai-alibaba.version}</version >
</dependency >
<dependency >
<groupId > com.alibaba.cloud.ai</groupId >
<artifactId > spring-ai-alibaba-starter-a2a-nacos</artifactId >
<version > ${spring-ai-alibaba.version}</version >
</dependency >
</dependencies >
配置文件 server:
port: 8081
spring:
application:
name: math-agent-service
ai:
dashscope:
api-key: ${AI_DASHSCOPE_API_KEY}
chat:
options:
model: qwen-max
alibaba:
a2a:
nacos:
server-addr: 127.0 .0 .1 :8848
registry:
enabled: true
namespace: dev
group: DEFAULT_GROUP
discovery:
enabled: true
namespace: dev
group: DEFAULT_GROUP
server:
enabled: true
card:
name: math_agent
description: "数学计算智能体"
version: "1.0.0"
logging:
level:
com.alibaba.cloud.ai: DEBUG
创建智能体 @Configuration
public class MathAgentConfig {
@Bean
public ReactAgent mathAgent (ChatModel chatModel, MathTools mathTools) {
return ReactAgent.builder()
.name("math_agent" )
.description("专业的数学计算智能体,可以进行加减乘除和复杂计算" )
.model(chatModel)
.instruction("你是一个专业的数学助手..." )
.tools(mathTools)
.build();
}
}
@Component
class MathTools {
@Tool(description = "计算两个数的和")
public double add (@ToolParam(description = "第一个数") double a, @ToolParam(description = "第二个数") double b) {
return a + b;
}
}
启动服务后,访问 Nacos 控制台查看 math_agent 服务是否已注册。
3.3 创建服务消费者
创建项目 <dependencies >
<dependency >
<groupId > org.springframework.boot</groupId >
<artifactId > spring-boot-starter-web</artifactId >
</dependency >
<dependency >
<groupId > com.alibaba.cloud.ai</groupId >
<artifactId > spring-ai-alibaba-agent-framework</artifactId >
<version > ${spring-ai-alibaba.version}</version >
</dependency >
<dependency >
<groupId > com.alibaba.cloud.ai</groupId >
<artifactId > spring-ai-alibaba-starter-a2a-nacos</artifactId >
<version > ${spring-ai-alibaba.version}</version >
</dependency >
</dependencies >
配置文件 server:
port: 8082
spring:
application:
name: consumer-service
ai:
alibaba:
a2a:
nacos:
server-addr: 127.0 .0 .1 :8848
discovery:
enabled: true
namespace: dev
group: DEFAULT_GROUP
创建消费者服务 @Service
public class MathConsumerService {
@Autowired
private AgentCardProvider agentCardProvider;
public String calculate (String question) {
A2aRemoteAgent mathAgent = A2aRemoteAgent.builder()
.name("math_agent" )
.agentCardProvider(agentCardProvider)
.build();
Optional<OverAllState> result = mathAgent.invoke(question);
return result.flatMap(state -> state.getLastMessage())
.map(msg -> msg.getContent())
.orElse("未获取到响应" );
}
}
创建 REST 控制器 @RestController
@RequestMapping("/api/math")
public class MathController {
@Autowired
private MathConsumerService mathService;
@PostMapping("/calculate")
public CalculateResponse calculate (@RequestBody CalculateRequest request) {
String answer = mathService.calculate(request.question());
return new CalculateResponse (request.question(), answer);
}
}
record CalculateRequest (String question) {}
record CalculateResponse (String question, String answer) {}
3.4 运行示例
启动 Nacos。
启动 Provider(终端 2)。
启动 Consumer(终端 3)。
测试调用:
curl -X POST http://localhost:8082/api/math/calculate \
-H "Content-Type: application/json" \
-d '{ "question": "计算 123 + 456 的结果" }'
4. 核心概念详解
4.1 AgentCard AgentCard 是智能体的'名片',包含了智能体的所有元信息。
字段说明 字段 类型 必需 说明 示例 name String 是 智能体名称,必须唯一 'customer_service' endpoint String 是 REST API 端点 'http://192.168.1.10:8081 ' description String 否 智能体功能描述 '智能客服机器人' version String 否 版本号 '1.0.0' capabilities List 否 支持的能力列表 ['tool_calling', 'streaming'] metadata Map 否 扩展元数据 {'team': 'support'}
最佳实践
命名规范 :建议使用蛇形命名(如 customer_service),清晰表达业务含义。
版本管理 :使用语义化版本(主版本。次版本。修订号)。
能力声明 :在 capabilities 中声明智能体支持的特性(如中文、流式响应),便于消费者筛选。
元数据扩展 :存储团队信息、性能指标、部署信息等,辅助路由决策。
4.2 AgentCardProvider AgentCardProvider 是服务发现的核心接口,负责查询和管理 AgentCard。
实现类
NacosAgentCardProvider :基于 Nacos 的动态服务发现,生产环境推荐。
StaticAgentCardProvider :基于静态配置的服务发现,适用于测试或离线场景。
使用示例 @Service
public class AgentDiscoveryService {
@Autowired
private AgentCardProvider agentCardProvider;
public void discoverAgents () {
Optional<AgentCard> mathAgent = agentCardProvider.getAgentCard("math_agent" );
List<AgentCard> allAgents = agentCardProvider.listAgentCards();
List<AgentCard> chineseAgents = agentCardProvider.findAgentCards(
card -> card.getCapabilities() != null && card.getCapabilities().contains("chinese" )
);
}
}
4.3 A2aRemoteAgent A2aRemoteAgent 是远程智能体的本地代理,提供与 ReactAgent 相同的接口。
创建远程智能体 A2aRemoteAgent remoteAgent = A2aRemoteAgent.builder()
.name("math_agent" )
.agentCardProvider(agentCardProvider)
.connectTimeout(Duration.ofSeconds(10 ))
.readTimeout(Duration.ofSeconds(30 ))
.maxRetries(3 )
.build();
调用方法
同步调用 :invoke() 返回 Optional<OverAllState>。
异步调用 :结合 CompletableFuture 实现非阻塞调用。
流式调用 :stream() 返回 Flux<NodeOutput>,适合实时反馈场景。
错误处理 捕获 A2aException 及其子类(如 AgentNotFoundException, AgentUnavailableException),区分不同错误场景进行友好提示或重试。
4.4 注册中心
为什么需要注册中心? 注册中心解决了分布式系统中的核心问题:服务发现、负载均衡、健康检查和动态扩缩容。没有它,我们需要硬编码服务地址,维护成本极高。
Nacos 核心概念
服务(Service) :一组提供相同功能的实例集合。
实例(Instance) :服务的具体运行单元(IP + Port)。
命名空间(Namespace) :隔离不同环境(dev/test/prod)。
分组(Group) :同一命名空间内的逻辑分组。
健康检查机制
心跳检查 :实例定期发送心跳,Nacos 判断存活。
主动健康检查 :Nacos 定期检查实例的健康端点。
Spring Boot Actuator :配置 /actuator/health 端点以配合 Nacos 检查。
5. Nacos 集成
5.1 Nacos 介绍 Nacos 是阿里巴巴开源的动态服务发现、配置管理和服务管理平台。选择 Nacos 的原因包括:经过双 11 验证、功能全面、高可用、易于使用以及与 Spring Cloud 无缝集成。
5.2 Nacos 安装与配置
Docker 部署(单机模式) docker run -d \
--name nacos \
-e MODE=standalone \
-p 8848:8848 \
nacos/nacos-server:latest
Docker Compose 部署(集群模式) 适用于生产环境,需配置 MySQL 持久化存储和多节点集群。
5.3 服务注册配置
基础配置 spring:
ai:
alibaba:
a2a:
nacos:
server-addr: 127.0 .0 .1 :8848
registry:
enabled: true
namespace: dev
group: DEFAULT_GROUP
server:
enabled: true
card:
name: my_agent
version: "1.0.0"
多环境配置 利用 Spring Profile 区分开发、测试和生产环境,分别配置不同的 Nacos 地址和命名空间。
5.4 服务发现配置 spring:
ai:
alibaba:
a2a:
nacos:
discovery:
enabled: true
healthy-only: true
cache-enabled: true
cache-ttl: 30s
6. 配置详解
6.1 完整配置示例 详细展示了 Nacos 连接、注册、发现、超时、重试、熔断及监控等全方位配置项。
6.2 注册配置参数 包括 registry.enabled, namespace, group, weight, heart-beat-interval 等关键参数说明。
6.3 发现配置参数 包括 discovery.enabled, load-balance-strategy, cache-ttl, watch-enabled 等参数说明。
6.4 网络配置 涉及超时控制(连接、读取、写入)、连接池配置(最大连接数、空闲时间)以及重试退避策略。
7. 服务注册
7.1 自动注册(推荐) 只需添加依赖并配置 registry.enabled=true,Spring Boot 启动时会自动扫描 ReactAgent Bean 并注册到 Nacos。
7.2 手动注册 通过 AgentRegistry 接口可以在代码中动态控制注册和注销过程,适用于特殊生命周期管理场景。
7.3 AgentCard 详解 深入解析了 AgentCard 的构建方式、Capabilities 的使用场景(如按能力筛选)以及 Metadata 的最佳实践(性能指标、业务信息、路由信息等)。
7.4 注册生命周期 介绍了注册过程中的事件监听(AgentRegisteredEvent, AgentUnregisteredEvent)以及优雅关闭的实现,确保服务下线时正确清理资源。
8. 服务发现
8.1 发现机制 描述了从缓存检查、Nacos 查询、健康过滤、负载均衡到缓存更新的完整流程。
8.2 查询服务 提供了基本查询(单个或多个)、高级查询(按版本、能力、元数据)以及批量查询和缓存预热的示例代码。
8.3 负载均衡 支持加权随机、轮询、一致性哈希等多种策略,并可自定义负载均衡器(如基于延迟选择)。
8.4 健康检查 解释了心跳检查和主动健康检查机制,以及如何配置 Spring Boot Actuator 和自定义健康指标来确保服务可靠性。
9. 远程智能体调用
9.1 创建远程智能体代理 展示了基础创建、完整配置(超时、重试、熔断)以及通过 Bean 注入的方式。
9.2 同步调用 包括简单调用、带配置的调用(会话 ID、元数据)、错误处理和超时控制策略。
9.3 异步调用 利用 CompletableFuture 实现并发调用多个智能体,或使用回调函数处理结果。
9.4 流式调用 演示了基础流式调用、带配置的流式调用、前端 SSE 对接以及流式调用的高级用法(限流、超时、组合流)。
相关免费在线工具 Keycode 信息 查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
Escape 与 Native 编解码 JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
JavaScript / HTML 格式化 使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
JavaScript 压缩与混淆 Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online
RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online