AgentScope Java 2.0 协议集成全景解析：A2A、AG-UI、Agent Protocol 三大开放协议实战指南

一、引言：协议层是智能体规模化的"最后一公里"

2025 年 4 月，Google 发布 A2A（Agent-to-Agent）协议；2025 年 5 月，CopilotKit 团队推出 AG-UI（Agent-User Interaction Protocol）。AI Agent 生态正在经历从"各自为政"到"协议互通"的关键转变。

但在实际落地中，企业面临的挑战更加复杂：

• 语言栈多样化：核心业务团队用 Java/Go，算法团队用 Python，跨语言协同困难
• 框架碎片化：LangChain、AutoGen、CrewAI、AgentScope 各有各的接口规范
• 前端适配重复造轮子：每个团队都在自定义 SSE 事件格式，无法复用前端组件

AgentScope Java 2.0 在 extensions-protocol 模块中提供了四大协议适配器，以独立 Maven 模块的形式实现"即插即用"的模块化集成：

这四大协议覆盖了智能体系统的三个交互维度：

┌─────────────────────────────────────────────────────────┐
│ 用户 / 前端应用 │
│ ↕ AG-UI（Agent ↔ User Interface） │
├─────────────────────────────────────────────────────────┤
│ 编排层 / 业务服务 │
│ ↕ Agent Protocol（Agent ↔ REST Client） │
├─────────────────────────────────────────────────────────┤
│ Agent 集群 │
│ ↕ A2A（Agent ↔ Agent） │
└─────────────────────────────────────────────────────────┘

二、A2A 协议集成：跨框架、跨语言的智能体互操作

2.1 协议背景

A2A（Agent-to-Agent Protocol）由 Google 于 2025 年 4 月发布，同年 6 月捐赠给 Linux Foundation，由 AWS、Cisco、Google、Microsoft、Salesforce、SAP 等共同维护。截至 2026 年，已有超过 150 家组织支持该协议。
其核心设计目标：

• 异构互操作：不同框架、不同厂商的 Agent 可以互相发现、通信和协作
• 不共享内存：Agent 之间无需共享工具、上下文或内部状态
• 基于现有标准：构建在 HTTP、JSON、SSE 之上，易于与现有技术栈集成

2.2 核心概念

💡 MCP 与 A2A 的关系：MCP 标准化了 Agent 如何调用工具（手和脚），A2A 标准化了 Agent 之间如何通信（嘴巴和耳朵）。两者互补，不是替代关系。

2.3 AgentScope Java 的 A2A 实现

AgentScope Java 提供了完整的 A2A Server + A2A Client 双端实现。
添加依赖

<dependency>
<groupId>io.agentscope</groupId>
<artifactId>agentscope-extensions-protocol-a2a</artifactId>
<version>${agentscope.version}</version>
</dependency>

A2A Server：将 Agent 包装为 A2A 服务端点

import io.agentscope.a2a.server.A2aServer;
import io.agentscope.agent.ReActAgent;

// 1. 构建 Agent
ReActAgent agent = ReActAgent.builder()
.name("TravelAssistant")
.description("帮助用户规划旅行行程")
.model(model)
.toolkit(toolkit)
.build();

// 2. 创建 A2A Server（Spring Boot 自动配置或编程式）
A2aServer a2aServer = A2aServer.builder()
.agent(agent)
.port(8080)
.build();

a2aServer.start();

启动后，Server 会自动暴露：

• GET /.well-known/agent.json → Agent Card（能力发现）
• POST / → A2A JSON-RPC 端点（Task 提交、消息发送）
• GET /events → SSE 流（流式事件推送）

A2A Client：调用远端 A2A Agent
AgentScope 支持两种客户端发现模式：
模式一：Well-Known URI 直连

import io.agentscope.a2a.client.A2aClient;

A2aClient client = A2aClient.builder()
.baseUrl("http://travel-agent:8080")
.build();

// 发送任务
Task task = client.sendTask(MessageSendParams.builder()
.message(Message.of("帮我规划一个东京五日游"))
.build());

// 订阅流式事件
client.subscribeEvents(task.getId(), event -> {
System.out.println(event.getType() + ": " + event.getData());
});

模式二：Nacos 注册中心发现

import io.agentscope.a2a.client.NacosAgentCardResolver;

// 通过 Nacos 自动发现可用的 A2A Agent
NacosAgentCardResolver resolver = NacosAgentCardResolver.builder()
.serverAddr("nacos-server:8848")
.namespace("agent-registry")
.build();

List<AgentCard> cards = resolver.resolve("travel");
A2aClient client = A2aClient.fromAgentCard(cards.get(0));

💡 Nacos 集成的价值：在企业级场景中，Agent 数量可能达到数十甚至上百个。通过 Nacos Agent Registry 实现统一注册与发现，让"调 Agent 像调微服务一样自然"。

2.4 协议栈四层模型

AgentScope 的 A2A 实现遵循协议栈四层设计：

2.5 生产实践要点

• 安全：Agent Card 中的 securitySchemes 字段声明认证要求（OAuth2、API Key 等）
• 超时控制：Task 执行可能耗时较长，建议配置合理的 timeout 与心跳机制
• 幂等性：taskId 作为唯一标识，重复提交同一 taskId 应返回已有 Task 而非重复创建
• 背压处理：流式事件订阅需考虑消费端处理能力，避免 SSE 缓冲区溢出

三、AG-UI 协议集成：Agent 与前端的标准化事件通信

3.1 协议背景

AG-UI（Agent-User Interaction Protocol）由 CopilotKit 团队于 2025 年 5 月推出，是一个开源、轻量、事件驱动的通信协议。其核心定位：

标准化 AI Agent 与前端 UI 的双向交互。

如果说 MCP 解决了"Agent 如何调用工具"，A2A 解决了"Agent 之间如何通信"，那么 AG-UI 补上了协议栈上缺失的最后一环：Agent 如何与人交互。
截至 2026 年 7 月，GitHub 上 ag-ui-protocol/ag-ui 仓库已有约 15.1k 星标、1.4k Fork。

3.2 核心设计原则

3.3 五类事件模型

AG-UI 将 Agent 运行过程拆分为五大类事件：

3.4 SSE 事件流示例

一次典型的 AG-UI 交互，前端收到的 SSE 事件流如下：

data:{"type":"RUN_STARTED","threadId":"thread-001","runId":"run-001"}

data:{"type":"TEXT_MESSAGE_START","messageId":"msg-001","role":"assistant"}

data:{"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-001","delta":"你好，"}

data:{"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-001","delta":"我是你的旅行助手。"}

data:{"type":"TEXT_MESSAGE_END","messageId":"msg-001"}

data:{"type":"TOOL_CALL_START","toolCallId":"tc-001","toolName":"search_flights"}

data:{"type":"TOOL_CALL_ARGS","toolCallId":"tc-001","delta":"{\\"from\\":\\"北京\\",\\"to\\":\\"东京\\"}"}

data:{"type":"TOOL_CALL_END","toolCallId":"tc-001"}

data:{"type":"TOOL_CALL_RESULT","toolCallId":"tc-001","result":"找到3个航班…"}

data:{"type":"STATE_DELTA","delta":[{"op":"add","path":"/flights","value":[…]}]}

data:{"type":"RUN_FINISHED","threadId":"thread-001","runId":"run-001"}

每条事件格式为 data:\\n\\n，两个换行符表示事件边界。

3.5 AgentScope Java 的 AG-UI 实现

添加依赖

<dependency>
<groupId>io.agentscope</groupId>
<artifactId>agentscope-extensions-protocol-agui</artifactId>
<version>${agentscope.version}</version>
</dependency>

核心机制
AgentScope 框架在流式调用过程中产生 28 种类型化事件，AG-UI 适配器负责将这些内部事件映射为 AG-UI 标准事件格式，并通过 SSE 推送给前端：

AgentScope 内部事件 → AG-UI Event Mapper → SSE Stream → 前端

关键特性

• 多 Agent 路由：支持在一次会话中路由到不同的 Agent 处理
• 中断与恢复：支持用户主动中断（RUN_CANCELED），以及断线重连后- 通过 STATE_SNAPSHOT 恢复
• 快照 + 增量：首次连接发送全量快照，后续仅推送增量变更，降低带宽消耗

3.6 前端接入示例

const eventSource = new EventSource('/ag-ui/run');

eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);

switch (data.type) {
case 'TEXT_MESSAGE_CONTENT':
appendToChat(data.messageId, data.delta);
break;
case 'TOOL_CALL_START':
showToolCallUI(data.toolName);
break;
case 'STATE_DELTA':
applyStatePatch(data.delta);
break;
case 'RUN_FINISHED':
hideLoadingIndicator();
break;
}
};

四、Agent Protocol 集成：将 Agent 暴露为标准 REST API

4.1 协议定位

Agent Protocol 是一种通用的 Agent 服务化协议，核心目标是：

将 Agent 暴露为标准 REST API，便于与现有微服务架构集成。

与 A2A 面向"Agent 间协作"不同，Agent Protocol 更偏向"Agent 作为服务被调用"的场景——即传统的 HTTP Client → Agent Server 模式。

4.2 核心 API 端点

4.3 AgentScope Java 实现

添加依赖

<dependency>
<groupId>io.agentscope</groupId>
<artifactId>agentscope-extensions-protocol-agent-protocol</artifactId>
<version>${agentscope.version}</version>
</dependency>

快速接入

import io.agentscope.protocol.AgentProtocolServer;

AgentProtocolServer server = AgentProtocolServer.builder()
.agent(agent)
.port(9090)
.build();

server.start();

启动后即可通过标准 HTTP 调用：

# 创建任务
curl -X POST http://localhost:9090/ap/tasks \\
-H "Content-Type: application/json" \\
-d '{"input": "帮我分析上周的销售数据"}'

# 查询任务状态
curl http://localhost:9090/ap/tasks/task-001

4.4 适用场景

• 已有微服务网关（如 Higress、Kong），需要将 Agent 纳入统一流量管控
• 非 AI 原生的业务系统需要通过 HTTP 调用 Agent 能力
• 需要与 CI/CD、监控系统等运维工具链集成
• 多语言客户端（Python、Go、Rust）需要统一调用入口

五、四大协议对比与选型指南

5.1 协议定位对比

5.2 选型决策树

你的场景是什么？
│
├─ 多个 Agent 需要互相委托任务？
│ └─ ✅ A2A
│
├─ 需要前端实时展示 Agent 执行过程（流式文本、工具调用可视化）？
│ └─ ✅ AG-UI
│
├─ 需要将 Agent 纳入现有微服务体系（REST 调用、网关管控）？
│ └─ ✅ Agent Protocol
│
├─ 需要兼容 OpenAI SDK / 已有 Chat Completions 客户端？
│ └─ ✅ Chat Completions Web
│
└─ 以上都需要？
└─ ✅ 组合使用，同一 Agent 可同时暴露多种协议端点

5.3 组合使用示例

// 同一个 Agent，同时暴露三种协议
ReActAgent agent = ReActAgent.builder()
.name("SmartAssistant")
.model(model)
.toolkit(toolkit)
.build();

// A2A Server：供其他 Agent 调用
A2aServer a2a = A2aServer.builder().agent(agent).port(8080).build();

// AG-UI：供前端实时交互
AgUiServer agui = AgUiServer.builder().agent(agent).port(8081).build();

// Agent Protocol：供微服务网关调用
AgentProtocolServer ap = AgentProtocolServer.builder().agent(agent).port(8082).build();

a2a.start();
agui.start();
ap.start();

六、架构全景：协议层在 AgentScope 中的位置

┌─────────────────────────────────────────────────────────────┐
│ extensions-protocol │
├──────────┬──────────┬──────────────┬────────────────────────┤
│ A2A │ AG-UI │Agent Protocol│ Chat Completions │
│(C+S) │ │ │ (OpenAI 兼容) │
├──────────┴──────────┴──────────────┴────────────────────────┤
│ agentscope-core │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ReActAgent│ │HarnessAgt│ │ Toolkit │ │ Event System │ │
│ └──────────┘ └──────────┘ └──────────┘ └───────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 基础设施层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ Nacos │ │ RocketMQ │ │ Higress │ │ AgentState │ │
│ │(注册发现) │ │(异步传输) │ │(AI网关) │ │ Store(状态) │ │
│ └──────────┘ └──────────┘ └──────────┘ └───────────────┘ │
└─────────────────────────────────────────────────────────────┘

七、生产环境最佳实践

7.1 安全与鉴权

• A2A：通过 Agent Card 的 securitySchemes 声明认证方式；生产环境建议启用 mTLS
• AG-UI：SSE 连接需携带 Token；考虑使用 Higress 网关做统一鉴权与限流
• Agent Protocol：标准 HTTP Header 鉴权（Bearer Token / API Key）

7.2 可观测性

• 所有协议适配器均接入 AgentScope 的 28 种类型化事件系统
• 建议对接 OpenTelemetry，实现全链路 Trace
• 对 A2A Task 的 state 变迁做指标采集（Submitted/Working/Completed/Failed 计数）

7.3 容错与重试

7.4 性能建议

• A2A 高吞吐场景考虑使用 RocketMQ 传输（AgentScope 已有官方适配），避免 SSE 长连接的资源占用
• AG-UI 前端渲染建议使用 虚拟列表 + 事件批量合并，避免高频 TEXT_MESSAGE_CONTENT 导致 DOM 抖动
• Agent Protocol 的 Task 状态查询建议增加缓存层，避免频繁查询执行中任务

八、总结

AgentScope Java 2.0 的协议集成层，通过四大标准化适配器，完整覆盖了智能体系统的三个交互维度：

这套协议体系的核心设计哲学是：让 Agent 像微服务一样被治理，像网页一样被交互，像 API 一样被调用。
对于正在构建多智能体系统的团队，建议按以下优先级逐步接入：