Spring AI Alibaba 57｜A2A 分布式智能体 · 基于 Nacos 的 A2A Registry

Nacos3 最新版本提供了 A2A AgentCard 模型的存储与推送支持，因此可以作为 A2A Registry 实现。Spring AI Alibaba 通过与 Nacos A2A Registry 集成，可以实现：

1. A2A Server AgentCard 自动注册到 Nacos A2A Registry
2. A2a Client 自动订阅发现可用 AgentCard，实现 AgentCard 调用的负载均衡

配置 Nacos Registry 和 Discovery

spring:
ai:
  alibaba:
    a2a:
      nacos:
        server-addr: 127.0.0.1:8848
        username: nacos
        password: nacos
        discovery:
          enabled: true   # 启用服务发现（查询其他 Agent）
        registry:
          enabled: true   # 启用服务注册（注册本地 Agent）
      server:
        version: 1.0.0
        card:
          name: data_analysis_agent
          description: 专门用于数据分析和统计计算的本地智能体
          provider:
            name: Spring AI Alibaba Documentation
            organization: Spring AI Alibaba

重要配置说明：

• registry.enabled: true – 必须启用才能将 Agent 注册到 Nacos（服务提供者）
• discovery.enabled: true – 启用后才能通过 AgentCardProvider 发现其他 Agent（服务消费者）
• server.card.name – 必须与 ReactAgent Bean 的 name 一致

完整示例

import com.alibaba.cloud.ai.graph.agent.ReactAgent;
import com.alibaba.cloud.ai.graph.agent.a2a.A2aRemoteAgent;
import com.alibaba.cloud.ai.graph.agent.a2a.AgentCardProvider;
import com.alibaba.cloud.ai.graph.OverAllState;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;

import java.util.Optional;

@Component
public class A2AExample {

  private final ChatModel chatModel;
  private final AgentCardProvider agentCardProvider;
  private final ReactAgent localDataAnalysisAgent;

  @Autowired
  public A2AExample(@Qualifier("dashscopeChatModel") ChatModel chatModel,
                    AgentCardProvider agentCardProvider,
                    @Qualifier("dataAnalysisAgent") ReactAgent localDataAnalysisAgent) {
      this.chatModel = chatModel;
      this.agentCardProvider = agentCardProvider;
      this.localDataAnalysisAgent = localDataAnalysisAgent;
  }

  public void runDemo() {
      // 1. 本地直连：验证本地注册的 ReactAgent 可用
      Optional<OverAllState> localResult = localDataAnalysisAgent.invoke(
          "请对上月销售数据进行趋势分析，并给出关键结论。"
      );
      localResult.ifPresent(state -> {
          System.out.println("本地调用成功");
      });

      // 2. 发现：通过 AgentCardProvider 从注册中心获取该 Agent 的 AgentCard
      A2aRemoteAgent remote = A2aRemoteAgent.builder()
              .name("data_analysis_agent")
              .agentCardProvider(agentCardProvider)  // 从 Nacos 自动获取 AgentCard
              .description("数据分析远程代理")
              .build();

      // 3. 远程调用：通过 A2aRemoteAgent 调用
      Optional<OverAllState> remoteResult = remote.invoke(
          "请根据季度数据给出同比与环比分析概要。"
      );
      remoteResult.ifPresent(state -> {
          System.out.println("远程调用成功");
      });
  }
}

验证本地 AgentCard

curl http://localhost:8080/.well-known/agent.json

验证 Nacos 注册

1. 打开 Nacos 控制台：http://localhost:8848/nacos
2. 登录（nacos/nacos）
3. 查看 A2A 服务注册维度，应该能看到注册的 Agent

注册与发现的区别

两者可独立配置，也可同时启用。当同时启用时：

• 作为提供者：注册本地 Agent 到 Nacos
• 作为消费者：可发现并调用其他已注册的 Agent（包括自己）

1. 依赖要求：

   需要添加 spring-ai-alibaba-starter-a2a-nacos 依赖
   确保 Nacos 服务正常运行

2. AgentCard 元数据：

   server.card.name 必须与 ReactAgent Bean 的 name 一致
   server.card.provider 可选，用于标识 Agent 提供者信息

3. 多 Agent 注册：

   默认情况下，只有一个 Agent Bean 会被注册
   如需注册多个 Agent，需运行多个应用实例，每个实例配置不同的 Agent

Agent 没有注册到 Nacos

• 检查 registry.enabled: true 是否配置
• 查看应用日志，确认 Nacos Registry AutoConfiguration 是否生效
• 验证 Nacos 连接配置（server-addr、username、password）

AgentCardProvider 无法发现 Agent

• 检查 discovery.enabled: true 是否配置
• 确认 Agent 已成功注册到 Nacos
• 验证 agent name 是否匹配

远程调用失败

• 确认目标 Agent 的 REST API 端点可访问
• 检查网络连接和防火墙配置
• 查看 A2A 消息传输日志

本文整理自 Spring AI Alibaba 官方文档《A2A 分布式智能体》：https://java2ai.com/docs/frameworks/agent-framework/advanced/a2a