一、A2A 是什么,解决什么问题

A2A(Agent-to-Agent) 是一种让"智能体之间互相调用"的协议约定。核心是 AgentCard(智能体名片):

  • 提供者把自己的能力(名称、描述、版本、访问 URL、支持的消息格式)描述成一张 AgentCard
  • 把 AgentCard 注册到 Registry(注册中心)
  • 消费者从 Registry 发现到 AgentCard,据此发起远程调用

类比理解:

A2A 概念微服务类比
AgentCard服务元数据 / 接口文档
Registry(注册)服务注册(Eureka/Nacos 服务注册)
Discovery(发现)服务发现 + 负载均衡
A2aRemoteAgentFeign / 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-addrNacos 地址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.nameAgentCard 名称必须等于 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端口
Providerdata_analysis_agent8080
Consumera2a_gateway_agent8081

六、踩坑记录(真实遇到)

坑 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 名创建者激活条件
nacosAgentCardProviderNacosA2aDiscoveryAutoConfigurationdiscovery.enabled: true(Nacos 发现,我们要的)
remoteAgentCardProviderA2aClientAgentCardProviderAutoConfiguration配置了 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 三个角色配置对照

场景registrydiscovery额外要求
纯提供者truefalseReactAgent Bean + server.card
纯消费者falsetrue无需 Agent(但仍需 ChatModel Bean)
双向(本工程)truetrueReactAgent 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 关键字段

字段说明
nameAgent 唯一名称(与 ReactAgent.name 一致)
description能力描述,供发现方判断是否合适
urlA2A 服务地址(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 负责打电话。

Logo

更多推荐