十六、Spring AIl Alibaba · 高级 A2A
一、A2A 是什么,解决什么问题
A2A(Agent-to-Agent) 是一种让"智能体之间互相调用"的协议约定。核心是 AgentCard(智能体名片):
- 提供者把自己的能力(名称、描述、版本、访问 URL、支持的消息格式)描述成一张 AgentCard
- 把 AgentCard 注册到 Registry(注册中心)
- 消费者从 Registry 发现到 AgentCard,据此发起远程调用
类比理解:
| A2A 概念 | 微服务类比 |
|---|---|
| AgentCard | 服务元数据 / 接口文档 |
| Registry(注册) | 服务注册(Eureka/Nacos 服务注册) |
| Discovery(发现) | 服务发现 + 负载均衡 |
A2aRemoteAgent | Feign / RestTemplate 客户端 |
/.well-known/agent.json | 健康检查 / OpenAPI 端点 |
为什么需要 Nacos 3? Nacos 3 新增了 A2A AgentCard 模型的存储与推送能力,天然可作为 A2A Registry,不需要自建注册中心。
二、Maven 依赖(pom.xml)
父工程统一版本管理
<properties>
<java.version>17</java.version>
<!-- Spring AI Alibaba 版本号前三位与 Spring AI 主版本对齐 -->
<spring-ai.version>1.1.2</spring-ai.version>
<spring-ai-alibaba.version>1.1.2.0</spring-ai-alibaba.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>${spring-ai.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-bom</artifactId>
<version>${spring-ai-alibaba.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
子模块依赖(提供者 / 消费者一致)
<dependencies>
<!-- Web:A2A Server 通过 /.well-known/agent.json 暴露 AgentCard -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- 关键:A2A + Nacos 注册发现 -->
<dependency>
<groupId>com.alibaba.cloud.ai</groupId>
<artifactId>spring-ai-alibaba-starter-a2a-nacos</artifactId>
</dependency>
</dependencies>
父工程已继承的公共依赖(不需要重复声明):
spring-ai-alibaba-agent-framework(ReactAgent、A2aRemoteAgent、AgentCardProvider)spring-ai-alibaba-starter-dashscope(DashScopeChatModel)
依赖内部长什么样(排查问题必备)
spring-ai-alibaba-starter-a2a-nacos-1.1.2.0.jar 的自动配置清单:
com.alibaba.cloud.ai.a2a.autoconfigure.client.A2aClientAgentCardProviderAutoConfiguration
com.alibaba.cloud.ai.a2a.autoconfigure.server.A2aServerAgentCardAutoConfiguration
com.alibaba.cloud.ai.a2a.autoconfigure.server.A2aServerHandlerAutoConfiguration
com.alibaba.cloud.ai.a2a.autoconfigure.server.A2aServerAutoConfiguration
com.alibaba.cloud.ai.a2a.autoconfigure.server.A2aServerRegistryAutoConfiguration
com.alibaba.cloud.ai.a2a.autoconfigure.nacos.NacosA2aRegistryAutoConfiguration
com.alibaba.cloud.ai.a2a.autoconfigure.nacos.NacosA2aDiscoveryAutoConfiguration
底层 A2A 协议实现是 io.github.a2asdk:a2a-java-sdk-spec:0.2.5.Beta2(io.a2a.spec.AgentCard / AgentProvider 等)。
三、配置(application.yml)
提供者完整配置
server:
port: 8080
spring:
application:
name: a2a-provider
ai:
dashscope:
api-key: ${AI_DASHSCOPE_API_KEY:sk-xxxx}
alibaba:
a2a:
nacos:
server-addr: 120.48.131.135:8848
username: nacos
password: nacos
# 命名空间:必须填「命名空间 ID」,不是名称
namespace: e1231dd9-a9d6-4c32-9333-0f9578718ce4
registry:
enabled: true # 注册中心:把本地 Agent 注册到 Nacos
discovery:
enabled: true # 注册中心:同时可发现其他 Agent
server:
version: 1.0.0
card:
# 必须与 ReactAgent Bean 的 name 完全一致
name: data_analysis_agent
description: 专门用于数据分析和统计计算的本地智能体
provider:
organization: Spring AI Alibaba
url: https://github.com/alibaba/spring-ai-alibaba
消费者配置(差异部分)
server:
port: 8081
spring:
ai:
alibaba:
a2a:
nacos:
server-addr: 120.48.131.135:8848
username: nacos
password: nacos
namespace: e1231dd9-a9d6-4c32-9333-0f9578718ce4
registry:
enabled: true
discovery:
enabled: true
server:
version: 1.0.0
card:
name: a2a_gateway_agent # 消费者自己也注册一个 Agent
description: 消费者侧网关智能体,同时作为 A2A 服务提供者注册
provider:
organization: Spring AI Alibaba
url: https://github.com/alibaba/spring-ai-alibaba
配置项逐条说明
| 配置项 | 作用 | 注意 |
|---|---|---|
nacos.server-addr | Nacos 地址 | Nacos 2.x/3.x 客户端使用 gRPC 9848(= 8848+1000),Docker 必须同时映射 8848 和 9848 |
nacos.username/password | 鉴权 | 默认 nacos/nacos |
nacos.namespace | 命名空间隔离 | 填 ID(e1231dd9-...),填名称无效 |
nacos.registry.enabled | 本地 Agent 注册 | 提供者必备 |
nacos.discovery.enabled | 发现其他 Agent | 消费者必备,未开启时 nacosAgentCardProvider 不存在 |
server.card.name | AgentCard 名称 | 必须等于 ReactAgent 的 name(),否则注册的卡与实际 Agent 对不上 |
server.card.provider | 提供者信息 | 绑定到 io.a2a.spec.AgentProvider record,只有 organization + url,url 必填 |
两者可独立配置:只开 registry = 纯提供者;只开 discovery = 纯消费者;都开 = 既是提供者又是消费者。
四、代码
4.1 提供者:定义本地 Agent
@Configuration
public class AgentConfig {
/** 与 a2a.server.card.name 保持一致 */
public static final String AGENT_NAME = "data_analysis_agent";
@Bean("dataAnalysisAgent")
public ReactAgent dataAnalysisAgent(DashScopeChatModel chatModel, DataAnalysisTools tools) {
return ReactAgent.builder()
.name(AGENT_NAME) // 关键:注册用的身份
.description("专门用于数据分析和统计计算的本地智能体")
.model(chatModel)
.systemPrompt("你是一个专业的数据分析专家……")
.methodTools(tools) // 挂工具,Agent 才会真正"干活"
.enableLogging(true)
.build();
}
}
工具类(@Tool 方法会被 ReactAgent 调用):
@Component
public class DataAnalysisTools {
@Tool(description = "对一组数字求和与平均值,返回统计结果")
public String sumAndAverage(@ToolParam(description = "逗号分隔的数字") String numbers) {
// ...
}
@Tool(description = "计算同比增长率:(本期 - 去年同期) / 去年同期 * 100%")
public String yearOverYear(double current, double lastYear) { /* ... */ }
@Tool(description = "计算环比增长率:(本期 - 上期) / 上期 * 100%")
public String quarterOverQuarter(double current, double previous) { /* ... */ }
}
4.2 消费者:发现 + 远程调用
@Service
public class RemoteAgentService {
private static final String REMOTE_AGENT_NAME = "data_analysis_agent";
private final AgentCardProvider agentCardProvider;
// 关键:starter 里有多个 AgentCardProvider Bean,必须按名注入
public RemoteAgentService(
@Qualifier("nacosAgentCardProvider") AgentCardProvider agentCardProvider) {
this.agentCardProvider = agentCardProvider;
}
public String callRemoteAgent(String message) throws GraphRunnerException {
A2aRemoteAgent remote = A2aRemoteAgent.builder()
.name(REMOTE_AGENT_NAME)
.agentCardProvider(agentCardProvider) // 从 Nacos 自动获取 AgentCard
.description("数据分析远程代理")
.build();
Optional<OverAllState> result = remote.invoke(message);
return result.map(this::lastAssistantText).orElse("远程 Agent 没有返回内容");
}
private String lastAssistantText(OverAllState state) {
Object raw = state.value("messages").orElse(null);
if (raw instanceof List<?> messages) {
for (int i = messages.size() - 1; i >= 0; i--) {
if (messages.get(i) instanceof AssistantMessage m && StringUtils.hasText(m.getText())) {
return m.getText();
}
}
}
return String.valueOf(raw);
}
}
4.3 Controller:一键触发
@RestController
@RequestMapping("/a2a")
public class ConsumerController {
private final RemoteAgentService remoteAgentService;
@GetMapping("/call")
public String call(@RequestParam("q") String message) throws GraphRunnerException {
return remoteAgentService.callRemoteAgent(message);
}
}
4.4 消费者也要注册时的最小条件
开启 registry.enabled: true 后,A2aServerAgentCardAutoConfiguration#agentCard(Agent, ...) 要求容器中有 com.alibaba.cloud.ai.graph.agent.Agent 类型 Bean,所以要额外加一个本地 Agent:
@Configuration
public class ConsumerAgentConfig {
public static final String AGENT_NAME = "a2a_gateway_agent";
@Bean("a2aGatewayAgent")
public ReactAgent a2aGatewayAgent(DashScopeChatModel chatModel) {
return ReactAgent.builder()
.name(AGENT_NAME) // 与 server.card.name 一致
.description("消费者侧网关智能体")
.model(chatModel)
.systemPrompt("你是 A2A 网关助手……")
.build();
}
}
4.5 官方"一体化"写法(本地 + 远程都调)
Optional<OverAllState> local = localDataAnalysisAgent.invoke("请对上月销售数据做趋势分析");
A2aRemoteAgent remote = A2aRemoteAgent.builder()
.name("data_analysis_agent")
.agentCardProvider(agentCardProvider)
.description("数据分析远程代理")
.build();
Optional<OverAllState> remoteResult = remote.invoke("请根据季度数据给出同比与环比分析概要");
五、运行与验证
# 1. 启动提供者(先启动,先注册)
mvn -pl SAA-Demo4-A2A-Provider spring-boot:run
# 验证本地 AgentCard
curl http://localhost:8080/.well-known/agent.json
# 2. 启动消费者
mvn -pl SAA-Demo5-A2A-Consumer spring-boot:run
curl http://localhost:8081/.well-known/agent.json
# 3. 触发 A2A 远程调用
curl "http://localhost:8081/a2a/call?q=请对上月销售数据100,200,300做趋势分析"
# 4. 直连本地 Agent(不经过 A2A 协议,用于对比)
curl "http://localhost:8080/agent/ask?q=对100,200,300求和"
Nacos 控制台 http://120.48.131.135:8848/nacos(nacos/nacos)→ 切到 a2a 命名空间 → A2A 注册维度应能看到:
| 应用 | 注册的 AgentCard | 端口 |
|---|---|---|
| Provider | data_analysis_agent | 8080 |
| Consumer | a2a_gateway_agent | 8081 |
六、踩坑记录(真实遇到)
坑 1:Provider 绑定失败 —— Parameter 'url' may be null
报错:
Failed to bind properties under 'spring.ai.alibaba.a2a.server.card.provider'
to io.a2a.spec.AgentProvider:
Reason: java.lang.IllegalArgumentException: Parameter 'url' may be null
原因:官方文档示例写的是
provider:
name: xxx
organization: yyy # 缺 url → 启动失败
但 1.1.2.0 底层 SDK 里 AgentProvider 是 record:
public record AgentProvider(String organization, String url) {}
- 没有
name字段(写了也只是被忽略/报未知字段) url必填,缺失直接抛IllegalArgumentException
正解:
provider:
organization: Spring AI Alibaba
url: https://github.com/alibaba/spring-ai-alibaba
教训:文档示例与依赖版本可能不一致,遇到绑定报错时直接反编译看目标类的真实结构。
坑 2:AgentCardProvider 注入歧义
IDE 报 “Could not autowire. There is more than one bean of type ‘AgentCardProvider’”。
原因:starter 里有 3 个该类型的 Bean:
| Bean 名 | 创建者 | 激活条件 |
|---|---|---|
nacosAgentCardProvider | NacosA2aDiscoveryAutoConfiguration | discovery.enabled: true(Nacos 发现,我们要的) |
remoteAgentCardProvider | A2aClientAgentCardProviderAutoConfiguration | 配置了 spring.ai.alibaba.a2a.client.card.wellKnownUrl(直连模式) |
localAgentCardProvider | 同上 | 配置了 spring.ai.alibaba.a2a.client.card.name(本地静态 card) |
正解:
public RemoteAgentService(@Qualifier("nacosAgentCardProvider") AgentCardProvider provider)
注意 Bean 名 =
@Bean方法名;IDE 自动补全有时给出错误大小写(如LocalAgentCardProvider),需自行核对。
坑 3:invoke() 抛受检异常
ReactAgent.invoke() / A2aRemoteAgent.invoke() 会抛 com.alibaba.cloud.ai.graph.exception.GraphRunnerException(受检异常),调用链上必须 throws 或 try-catch,否则编译失败。
坑 4:命名空间填错
Nacos 命名空间要填ID(e1231dd9-a9d6-4c32-9333-0f9578718ce4),不是名称 a2a。填名称会被当作不存在的 namespace 处理,注册和发现都"看不到东西"。
坑 5:Nacos 端口没映射全
Docker 只映射 8848 不够。Nacos 2.x/3.x 客户端走 gRPC 9848 端口,必须一起映射:
0.0.0.0:8848->8848/tcp, 0.0.0.0:9848->9848/tcp
坑 6:多 Agent 注册限制
默认只有一个 Agent Bean 会被注册。需要注册多个 Agent 时,要么运行多个应用实例(各配不同 card.name),要么用多个不同 server.card 的部署单元。
七、知识点整理
7.1 三个角色配置对照
| 场景 | registry | discovery | 额外要求 |
|---|---|---|---|
| 纯提供者 | true | false | ReactAgent Bean + server.card |
| 纯消费者 | false | true | 无需 Agent(但仍需 ChatModel Bean) |
| 双向(本工程) | true | true | ReactAgent Bean + server.card |
7.2 调用链
Consumer 业务代码
↓ A2aRemoteAgent.builder().name("data_analysis_agent")
↓ .agentCardProvider(nacosAgentCardProvider)
Nacos A2A Registry(namespace = a2a)
↓ 返回 AgentCard(含提供者 url / skills / capabilities)
A2A Client 发起 JSON-RPC 调用
↓
Provider A2A Server(8080 / .well-known/agent.json)
↓ GraphAgentExecutor → ReactAgent → Tool 调用 → LLM
返回结果 OverAllState(messages 中含 AssistantMessage)
7.3 AgentCard 关键字段
| 字段 | 说明 |
|---|---|
name | Agent 唯一名称(与 ReactAgent.name 一致) |
description | 能力描述,供发现方判断是否合适 |
url | A2A 服务地址(Server 侧通常自动生成,可用 card.url 覆盖) |
version | 版本号 |
provider | {organization, url} |
capabilities | 流式、推送等能力声明 |
skills | 技能列表 |
defaultInputModes / defaultOutputModes | 支持的输入输出类型 |
7.4 A2A vs 本地直调
| 维度 | 本地直调 | A2A 远程调用 |
|---|---|---|
| 代码 | reactAgent.invoke(q) | A2aRemoteAgent.invoke(q) |
| 依赖 | 同一 JVM | 跨进程 / 跨机器 / 跨团队 |
| 发现 | 无 | Nacos Registry 自动发现 |
| 负载均衡 | 无 | AgentCardProvider 选可用实例 |
| 故障隔离 | 差(同一进程) | 好 |
7.5 常用启动/排错命令
# 只编译指定模块
mvn -q -pl SAA-Demo4-A2A-Provider,SAA-Demo5-A2A-Consumer compile -DskipTests
# 查看真实生效的自动配置
mvn dependency:tree -pl SAA-Demo5-A2A-Consumer
# 反编译依赖类(排查绑定/Bean 问题最有效)
# 解包 jar 后 javap -p -classpath <解包目录> 全限定类名
# 查看 Nacos 容器端口映射
docker ps --format "{{.Names}} {{.Ports}}"
八、一句话总结
AgentCard 是名片,Nacos 是通讯录,registry 负责发名片,discovery 负责查通讯录,A2aRemoteAgent 负责打电话。
更多推荐



所有评论(0)