agentscope-ai / agentscope-ai/agentscope-java

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

未關閉
#1,209 1 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視
area/ext/integration enhancement
主要語言
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 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。