Skip to content

feat(a2a): 完善 A2A 1.0 适配与可持久化 HITL#2311

Draft
lzbjut wants to merge 8 commits into
agentscope-ai:mainfrom
lzbjut:codex/a2a-1.0-durable-hitl
Draft

feat(a2a): 完善 A2A 1.0 适配与可持久化 HITL#2311
lzbjut wants to merge 8 commits into
agentscope-ai:mainfrom
lzbjut:codex/a2a-1.0-durable-hitl

Conversation

@lzbjut

@lzbjut lzbjut commented Jul 20, 2026

Copy link
Copy Markdown

背景

AgentScope Java 2.x 已提供类型化的 AgentEvent 流和 HITL 事件,但现有 A2A 模块仍使用 1.0 之前的 Java SDK,并保留了一部分旧事件适配逻辑。本 PR 提供一套完整的 A2A 1.0 适配实现,并补齐远程 HITL 的暂停、恢复与可选持久化协调能力。

主要改动

  • 将 A2A client/server 从 io.github.a2asdk:*:0.3.3.Final 迁移到 org.a2aproject.sdk:*:1.0.0.Final,protobuf runtime 对齐到 4.33.2
  • Server 直接消费 AgentEvent,将 text、thinking、tool use/result、子 Agent source 和终态映射为 A2A 1.0 artifact/status。
  • Client/Server 分别使用明确的终态状态机,保证 final、hook 和 sink completion exactly-once,并显式处理缺失最终结果。
  • 为 user confirmation 和 external tool execution 增加可序列化的 handoff、resume(...)cancelHandoff(...) API;原有 A2aAgent.call() 保持可用。
  • 将 HITL resume admission 前移到 SDK executor 调度之前,错误 token、错误 response set 或 lease 冲突不会污染原有 Task。
  • HITL 默认关闭;启用后支持单进程 local 模式,并提供可组合的 durability SPI。
  • 新增可选的 Redisson 参考实现,用于 A2A Task、handoff、token claim、session lease 和 TTL;AgentStateStore 仍由业务应用负责。
  • 补充中英文 A2A 1.0、local HITL、durable HITL、恢复安全边界和接入示例。

与现有工作的关系

兼容性与边界

  • SDK groupId、Java package 和 server API 均发生变化,因此 SDK 1.0 迁移属于 breaking refactor,而非单纯版本号升级。
  • AgentScope 专属的 block/source 信息仅通过可选 metadata 传递;第三方 A2A peer 仍按标准字段 best-effort 兼容。
  • 暂停会结束当前流,恢复是在相同 task/context 上发起的新请求,不持久化实时 SSE 事件流。
  • durable 模式强验证 A2A 控制面;AgentStateStore 的跨副本可达性由应用保证。
  • 不增加 in-task authentication 语义,因为 AgentScope 2.x 当前没有认证恢复契约。
  • token claim 保证单次 resume admission,但不承诺任意崩溃点下外部副作用 exactly-once。

验证

  • 全 reactor mvn clean verify:85 个 reactor 模块全部成功;7,597 tests,0 failures,0 errors,168 skipped。
  • client/server、local HITL、Redis durability、并发 claim、重放拒绝、错误 admission 不污染 Task、跨端 round-trip 测试。
  • A2A SDK 仅 1.0.0.Final,protobuf-java/-util 仅 4.33.2
  • Redis provider 进入公共 BOM,但明确不进入 agentscope-all;主 A2A Starter 不传递 Redis/Redisson。
  • 中英文文档示例与公共 API 对齐。

Closes #2270

guslegend0510 and others added 7 commits July 20, 2026 10:39
Migrate the A2A dependency groupId from io.github.a2asdk to org.a2aproject.sdk, update Java packages and SDK task/executor APIs, and preserve AgentScope-facing builders and cards.

Adopt the pre-HITL AgentEvent adapter and protobuf 4.33.2 runtime. This is a breaking API migration, not a version-only build change.
@jujn

jujn commented Jul 20, 2026

Copy link
Copy Markdown
Collaborator

@lzbjut 你好,有联系方式不?可以发我主页邮箱,我拉你进官方群

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

完善 AgentScope 2.x 的 A2A 1.0 适配与可持久化 HITL

3 participants