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

[flystar32]

背景

A2A 协议已于 2026-03-12 正式发布 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）的 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）
• 兼容层刚进入 PRD 阶段（PR #785，2026-04-09），代码尚未开发

相关链接

• A2A 1.0.0 Release Notes
• A2A What's New in v1.0
• A2A 向后兼容策略讨论
• a2a-java SDK 0.3/1.0 共存 Issue
• a2a-java SDK 0.3 兼容层 PRD