A2A Java 示例

克隆代码

git clone https://github.com/google-a2a/a2a-samples
cd a2a-samples/samples/java

本项目是 Agent2Agent (A2A) 协议的 Java 实现示例，提供完整的客户端和服务端 SDK，以及一个 AI 驱动的翻译服务演示应用程序。

项目架构

本项目采用 Maven 多模块架构，包含以下三个核心模块：

samples/java/
├── model/          # A2A 协议数据模型
├── server/         # A2A 服务端 SDK 和翻译服务
├── client/         # A2A 客户端 SDK 和示例代码
└── pom.xml         # 父级 Maven 配置文件

模块详情

🎯 Model 模块 (model/)

A2A 协议的核心数据模型，为 JSON-RPC 2.0 和 A2A 协议提供完整的数据结构：

• 消息模型: Message, Part, TextPart, Artifact
• 任务模型: Task, TaskStatus, TaskState
• 代理模型: AgentCard, AgentCapabilities, AgentSkill
• JSON-RPC 模型: JSONRPCRequest, JSONRPCResponse, JSONRPCError
• 事件模型: TaskStatusUpdateEvent, TaskArtifactUpdateEvent

🚀 Server 模块 (server/)

基于 Spring Boot 的 A2A 服务端 SDK，集成 Spring AI 框架：

• 核心组件:

  • A2AServer: 管理代理行为的主服务器类
  • A2AController: 实现 A2A 协议端点的 REST 控制器
  • TaskHandler: 任务处理接口
  • A2AServerConfiguration: AI 翻译机器人配置

• 主要特性:

  • 完整的 JSON-RPC 2.0 支持
  • 代理卡片发布 (/.well-known/agent-card)
  • 任务管理（发送、查询、取消）
  • 流式响应支持（Server-Sent Events）
  • Spring AI 集成，支持 OpenAI 和其他模型

📱 Client 模块 (client/)

纯 Java A2A 客户端 SDK，包含翻译客户端示例：

• 核心组件:

  • A2AClient: 处理所有 A2A 操作的主客户端类
  • StreamingEventListener: 流式事件监听器接口
  • A2AClientException: A2A 特定异常处理
  • A2AClientExample: 完整的翻译客户端示例

• 主要特性:

  • JSON-RPC 2.0 客户端实现
  • 代理发现和能力查询
  • 同步/异步任务操作
  • 流式响应处理
  • 连接池和错误恢复

核心功能实现

🤖 AI 翻译服务

项目实现了一个智能翻译代理，支持多语言翻译：

翻译逻辑:

• 中文 → 英文
• 英文 → 中文
• 其他语言 → 英文

技术特性:

• 基于 Spring AI ChatClient
• 支持 OpenAI、Azure OpenAI 和其他模型
• 上下文感知的自然语言翻译
• 实时流式响应

🔄 A2A 协议实现

完整实现 A2A 协议规范：

核心操作:

• tasks/send: 发送任务消息
• tasks/get: 查询任务状态
• tasks/cancel: 取消任务执行

协议特性:

• JSON-RPC 2.0 通信
• 代理能力发现
• 任务状态跟踪
• 流式事件推送
• 标准化错误代码

📡 通信机制

同步通信:

• HTTP POST /a2a - 标准 JSON-RPC 请求
• HTTP GET /.well-known/agent-card - 代理信息检索

流式通信:

• HTTP POST /a2a/stream - Server-Sent Events
• 实时任务状态更新
• 自动重连和错误恢复

如何运行

要求

• Java: 17 或更高版本

步骤 1: 编译项目

在项目根目录执行编译：

cd samples/java
./mvnw clean install -DskipTests

步骤 2: 配置环境变量

设置 AI 模型相关的环境变量（翻译功能必需）：

# OpenAI 配置
export OPENAI_API_KEY="your-openai-api-key"
export OPENAI_BASE_URL="https://api.openai.com"
export OPENAI_CHAT_MODEL="gpt-4o"

# 或 GCP OpenAI 配置
export OPENAI_API_KEY="your-gcp-api-key"
export OPENAI_BASE_URL="https://{location}-aiplatform.googleapis.com/v1/projects/{project_id}/locations/{location}/endpoints/openapi"
export OPENAI_CHAT_MODEL="gemini-2.5-pro-preview-05-06"

OpenRouter 配置

export OPENAI_API_KEY="sk-or-v1-"
export OPENAI_BASE_URL="https://openrouter.ai/api"
export OPENAI_CHAT_MODEL="openai/gpt-4o-2024-11-20"

注意 OPENAI_BASE_URL，URL 中没有 /v1。

步骤 3: 启动翻译服务器

启动 A2A 翻译服务器：

cd server
../mvnw spring-boot:run

服务器将在 http://localhost:8080 启动，提供以下端点：

• http://localhost:8080/.well-known/agent-card - 代理信息
• http://localhost:8080/a2a - A2A 协议端点
• http://localhost:8080/a2a/stream - 流式端点

验证代理卡片:

• A2A 协议验证器
• 指南: 如何验证您的代理卡片

步骤 4: 运行翻译客户端

在新的终端窗口中，运行客户端示例：

cd client
../mvnw exec:java -Dexec.mainClass="com.google.a2a.client.A2AClientExample"

时序图

以下时序图展示了基于 A2AClientExample.java 的 A2A Java 示例应用程序的完整交互流程：

sequenceDiagram
    participant Example as A2AClientExample
    participant Client as A2AClient
    participant Server as A2A Server<br/>(localhost:8080)
    
    Note over Example,Server: A2A Java 示例时序图
    
    %% 1. 初始化客户端
    Example->>Client: new A2AClient("http://localhost:8080")
    activate Client
    
    %% 2. 获取代理卡片
    Example->>Client: getAgentCard()
    Client->>Server: GET /.well-known/agent-card
    Server-->>Client: AgentCard (name, description, version, skills)
    Client-->>Example: AgentCard
    Note over Example: 打印代理信息
    
    %% 3. 法语到中文翻译
    Example->>Client: sendTask(frenchToChineseParams)
    Note right of Example: TextPart: "Bonjour le monde!<br/>Comment allez-vous?"
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/send
    Server-->>Client: Task (id, status, history)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: 打印翻译结果
    
    %% 4. 中文到英文翻译
    Example->>Client: sendTask(chineseParams)
    Note right of Example: TextPart: "你好，世界！<br/>欢迎使用AI翻译机器人。"
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/send
    Server-->>Client: Task (id, status, history)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: 打印翻译结果
    
    %% 5. 流式翻译
    Example->>Client: sendTaskStreaming(frenchParams, StreamingEventListener)
    Note right of Example: TextPart: "Bonjour le monde!<br/>Comment allez-vous?"
    Client->>Server: POST /a2a/stream<br/>Server-Sent Events
    activate Server
    
    loop 流式响应
        Server-->>Client: SSE Event (翻译进度)
        Client-->>Example: onEvent(event)
        Note over Example: 打印实时翻译事件
    end
    
    Server-->>Client: SSE Complete
    deactivate Server
    Client-->>Example: onComplete()
    Note over Example: 流式翻译完成
    
    %% 6. 查询任务状态
    Example->>Client: getTask(queryParams)
    Note right of Example: 查询法语翻译任务状态
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/get
    Server-->>Client: Task (更新状态)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: 打印任务状态
    
    %% 7. 发送要取消的任务
    Example->>Client: sendTask(cancelParams)
    Note right of Example: TextPart: "Diese Übersetzung<br/>wird abgebrochen." (德语)
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/send
    Server-->>Client: Task (id, status)
    Client-->>Example: JSONRPCResponse<Task>
    
    %% 8. 取消任务
    Example->>Client: cancelTask(cancelTaskParams)
    Client->>Server: POST /a2a<br/>JSON-RPC: tasks/cancel
    Server-->>Client: Task (已取消状态)
    Client-->>Example: JSONRPCResponse<Task>
    Note over Example: 打印取消结果
    
    deactivate Client
    Note over Example,Server: 示例程序执行完成

关键交互模式

时序图展示了以下核心交互模式：

1. 客户端初始化: 创建连接到本地服务器的 A2AClient 实例
2. 代理发现: 通过 /.well-known/agent-card 端点检索代理信息
3. 多语言翻译示例:
   • 法语 → 中文翻译
   • 中文 → 英文翻译
   • 德语 → 英文流式翻译
4. 任务管理:
   • 查询任务状态
   • 取消任务执行

通信机制

• 同步翻译: 使用 POST /a2a 端点和 JSON-RPC 请求
• 流式翻译: 使用 POST /a2a/stream 端点和 Server-Sent Events (SSE)
• 状态查询: 使用 tasks/get 方法检查任务执行状态
• 任务取消: 使用 tasks/cancel 方法取消运行中的任务

API 使用示例

获取代理信息

curl -X GET http://localhost:8080/.well-known/agent-card \
  -H "Accept: application/json"

发送翻译任务

curl -X POST http://localhost:8080/a2a \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "request-1",
    "method": "tasks/send",
    "params": {
      "id": "translation-task-1",
      "message": {
        "messageId": "msg-1",
        "kind": "message",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello, world!"
          }
        ]
      }
    }
  }'

流式翻译

curl -X POST http://localhost:8080/a2a/stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": "stream-request-1",
    "method": "tasks/send",
    "params": {
      "id": "streaming-translation-task",
      "message": {
        "messageId": "stream-msg-1",
        "kind": "message",
        "role": "user",
        "parts": [
          {
            "kind": "text",
            "text": "Hello world!"
          }
        ]
      }
    }
  }'