Spring AI Alibaba A2A 分布式智能体通信实战指南

架构分为三层：

1. 应用层：包含各个具体的智能体（Agent A, B, C）。
2. A2A 框架层：包含 Server（服务端）和 Client（客户端），负责暴露 REST API 和处理远程调用。
3. 基础设施层：注册中心（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 工作原理

服务注册流程

1. Spring Boot 应用启动，加载配置并初始化 Bean。
2. A2aServerAutoConfiguration 扫描 ReactAgent Bean。
3. 为每个 ReactAgent 创建 REST 端点。
4. 构造 AgentCard。
5. 向 Nacos 注册服务。
6. 启动心跳线程，每 5 秒发送一次心跳。

服务发现流程

1. 创建 A2aRemoteAgent 时，根据名称查询 AgentCard。
2. NacosAgentCardProvider 从 Nacos 获取服务实例列表。
3. 应用负载均衡策略选择一个健康实例。
4. 构造 AgentCard 并缓存（默认 30 秒）。

远程调用流程

1. 获取 AgentCard（从缓存或 Nacos）。
2. 构造 HTTP 请求（POST /api/a2a/{agentName}）。
3. 发送到远程服务。
4. 远程服务查找本地 ReactAgent 并调用。
5. 接收响应并解析。
6. 处理错误（超时重试、切换实例等）。

2.4 通信协议

REST API

A2A 使用标准的 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 启动单机模式：

docker run -d \
  --name nacos \
  -e MODE=standalone \
  -p 8848:8848 \
  -p 9848:9848 \
  nacos/nacos-server:latest

访问 http://localhost:8848/nacos，默认用户名密码均为 nacos。

3.2 创建服务提供者

创建 Maven 项目

pom.xml 依赖配置：

<dependencies>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Agent Framework -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-agent-framework</artifactId>
        <version>${spring-ai-alibaba.version}</version>
    </dependency>
    <!-- DashScope -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
        <version>${spring-ai-alibaba.version}</version>
    </dependency>
    <!-- A2A with Nacos -->
    <dependency>
        <groupId>com.alibaba.cloud.ai</groupId>
        <artifactId>spring-ai-alibaba-starter-a2a-nacos</artifactId>
        <version>${spring-ai-alibaba.version}</version>
    </dependency>
</dependencies>

配置文件

application.yml：

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 创建服务消费者

创建项目

pom.xml 只需引入 A2A 客户端依赖：

<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>

配置文件

application.yml：

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 运行示例

1. 启动 Nacos。
2. 启动 Provider（终端 2）。
3. 启动 Consumer（终端 3）。
4. 测试调用：

curl -X POST http://localhost:8082/api/math/calculate \
  -H "Content-Type: application/json" \
  -d '{ "question": "计算 123 + 456 的结果" }'

预期返回计算结果。查看日志可追踪完整的调用链路。

4. 核心概念详解

4.1 AgentCard

AgentCard 是智能体的'名片'，包含了智能体的所有元信息。

字段说明

最佳实践

1. 命名规范：建议使用蛇形命名（如 customer_service），清晰表达业务含义。
2. 版本管理：使用语义化版本（主版本。次版本。修订号）。
3. 能力声明：在 capabilities 中声明智能体支持的特性（如中文、流式响应），便于消费者筛选。
4. 元数据扩展：存储团队信息、性能指标、部署信息等，辅助路由决策。

4.2 AgentCardProvider

AgentCardProvider 是服务发现的核心接口，负责查询和管理 AgentCard。

实现类

• NacosAgentCardProvider：基于 Nacos 的动态服务发现，生产环境推荐。
• StaticAgentCardProvider：基于静态配置的服务发现，适用于测试或离线场景。

使用示例

@Service
public class AgentDiscoveryService {
    @Autowired
    private AgentCardProvider agentCardProvider;

    public void discoverAgents() {
        // 1. 获取特定智能体
        Optional<AgentCard> mathAgent = agentCardProvider.getAgentCard("math_agent");
        
        // 2. 列出所有智能体
        List<AgentCard> allAgents = agentCardProvider.listAgentCards();
        
        // 3. 按条件查找（例如支持中文的智能体）
        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 对接以及流式调用的高级用法（限流、超时、组合流）。