A2A Java 示例

sing1ee2025-06-05 10:32

克隆代码

bash 复制代码 
git clone https://github.com/google-a2a/a2a-samples
cd a2a-samples/samples/java

本项目是 Agent-to-Agent (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: 编译项目

在项目根目录执行编译：

bash 复制代码 
cd samples/java
./mvnw clean install -DskipTests

步骤 2: 配置环境变量

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

bash 复制代码 
# 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 配置

bash 复制代码 
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 翻译服务器：

bash 复制代码 
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 - 流式端点

验证代理卡片:

步骤 4: 运行翻译客户端

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

bash 复制代码 
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 使用示例

获取代理信息

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

发送翻译任务

bash 复制代码 
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!"
          }
        ]
      }
    }
  }'

流式翻译

bash 复制代码 
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!"
          }
        ]
      }
    }
  }'

A2A Java

相关推荐
sing1ee4 天前
基于 A2A 协议的 LlamaIndex 文件聊天工作流
agent·a2a
微学AI25 天前
大模型的应用中A2A（Agent2Agent）架构的部署过程，A2A架构实现不同机器人之间的高效通信与协作
人工智能·架构·机器人·a2a
MCP星球2 个月前
我们离Agent终极形态又近了一步：全球首个支持谷歌A2A（Agent-to-Agent)协议的智能体注册网站上线Product Hunt，未来智能体协作网络
ai·agent·智能体·智能体协作·a2a·a2a协议·agent network·智能体网络·谷歌a2a·agent2agent
AlfredZhao2 个月前
揭秘AI编排爆火真相：从"人工智障"到"真正智能"的关键一跃
ai·agent·mcp·a2a
一个处女座的程序猿2 个月前
LLMs之Agent之A2A：A2A的简介、安装和使用方法、案例应用之详细攻略
a2a
稳稳C92 个月前
Google A2A协议，是为了战略性占领标准？
人工智能·google·agent·mcp·a2a
热门推荐
01基于STM32的智能电池管理系统02KGG转MP3工具|非KGM文件|解密音频03YOLOv8入门 | 重要性能衡量指标、训练结果评价及分析及影响mAP的因素【发论文关注的指标】04海康Visionmaster-常见问题排查方法-启动阶段05从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑06【SpeedAI科研小助手】2分钟极速解决知网维普重复率、AIGC率过高，一键全文降！文件格式不变，公式都保留的！07VMware虚拟机安装Win7专业版保姆级教程（附镜像包）08DeepSeek各版本说明与优缺点分析09组基轨迹建模 GBTM的介绍与实现（Stata 或 R）10柬埔寨语翻译通App，一款真正实现高棉语翻译、语音识别和中柬双语无障碍交流的应用程序。