agentscope-ai / agentscope-ai/agentscope-java
[Feat]: A2A 协议升级 0.3.0 → 1.0.0 跟踪
- 主要语言
- Java
- 星标
- 5.6k
- 派生
- 1.3k
- 平均合并
- 4 天 12 小时
- 30 天内合并 PR
- 77
描述
## 背景
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)
贡献指南
评估
这个 Issue 还没有评估数据。