agentscope-ai / agentscope-ai/agentscope-java

[Feat]: A2A 协议升级 0.3.0 → 1.0.0 跟踪

Đang mở
#1,209 1 bình luận 0 reaction 0 người được giao Xem trên GitHub
area/ext/integration enhancement
Ngôn ngữ chính
Java
Star
5.6k
Fork
1.3k
Merge trung bình
4 ngày 12 giờ
Pull request đã merge (30 ngày)
77

Mô tả

## 背景

A2A 协议已于 2026-03-12 正式发布 [v1.0.0](https://github.com/a2aproject/A2A/releases/tag/v1.0.0),这是首个正式版本。当前 agentscope-java 对接的是 A2A 0.3.0 协议(SDK 版本 `io.github.a2asdk:0.3.3.Final`),需要规划升级路径。

## 当前状态

| 项目 | 当前值 |
|------|--------|
| 协议版本(protocolVersion) | `0.3.0`(硬编码于 `AgentScopeAgentCardConverter`) |
| SDK 依赖 | `io.github.a2asdk:0.3.3.Final` |
| 传输协议 | JSON-RPC over HTTP + SSE |

## 0.3.0 → 1.0.0 是破坏性升级

两个版本在 wire-format 层面不兼容,1.0.0 Client 无法直接调用 0.3.0 Server,反之亦然。主要 breaking changes:

### 数据模型变更

- **AgentCard 结构重构**:`url` + `preferredTransport` + `additionalInterfaces` 合并为 `supportedInterfaces`;`protocolVersion` 从 AgentCard 移至 `AgentInterface`;`supportsAuthenticatedExtendedCard` 移至 `capabilities.extendedAgentCard`;`security` 重命名为 `securityRequirements`
- **TaskState 枚举格式变更**:从 kebab-case(`submitted`/`working`/`completed`)变为 SCREAMING_SNAKE_CASE(`TASK_STATE_SUBMITTED`/`TASK_STATE_WORKING`/`TASK_STATE_COMPLETED`),新增 `TASK_STATE_REJECTED` 和 `TASK_STATE_AUTH_REQUIRED`
- **Role 枚举格式变更**:`user`/`agent` → `ROLE_USER`/`ROLE_AGENT`
- **Part 结构扁平化**:去掉 `kind` 鉴别字段,改用 JSON member name 做多态判断;`name` → `filename`
- **Message**:`messageId` 变为必填,新增 `extensions`、`referenceTaskIds`

### 操作/方法变更

- `tasks/resubscribe` → `tasks/subscribe`
- `tasks/pushNotificationConfig/set` → `tasks/pushNotificationConfig/create`
- 新增 `tasks/list`(含分页和过滤)、`agent/extendedCard`
- 新增 `A2A-Version` 请求头(必填),Server 需根据版本处理请求

### 其他

- 新增多租户支持(`tenant` 字段)
- `SendMessageConfiguration` 新增 `returnImmediately` 控制阻塞模式
- `TaskStatusUpdateEvent` 移除 `final` 字段,新增必填 `contextId`
- `stateTransitionHistory` 从 capabilities 中移除

## 上游 SDK 状态

a2a-java SDK([a2aproject/a2a-java](https://github.com/a2aproject/a2a-java))的 1.0.0 **尚未 GA**:

- 最新版本为 `1.0.0.Alpha4`(2026-03-16),Pre-release 状态
- Alpha4 起 **groupId 从 `io.github.a2asdk` 变更为 `org.a2aproject.sdk`**,所有 import 需要修改
- SDK 当前 **没有实现 0.3 向后兼容**([Issue #762](https://github.com/a2aproject/a2a-java/issues/762))
- 兼容层刚进入 PRD 阶段([PR #785](https://github.com/a2aproject/a2a-java/pull/785),2026-04-09),代码尚未开发

## 相关链接

- [A2A 1.0.0 Release Notes](https://github.com/a2aproject/A2A/releases/tag/v1.0.0)
- [A2A What's New in v1.0](https://github.com/a2aproject/A2A/blob/main/docs/whats-new-v1.md)
- [A2A 向后兼容策略讨论](https://github.com/a2aproject/A2A/discussions/1416)
- [a2a-java SDK 0.3/1.0 共存 Issue](https://github.com/a2aproject/a2a-java/issues/762)
- [a2a-java SDK 0.3 兼容层 PRD](https://github.com/a2aproject/a2a-java/pull/785)

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Đánh giá

Issue này chưa được đánh giá.

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.