agentscope-ai / agentscope-ai/agentscope-java
完善 AgentScope 2.x 的 A2A 1.0 适配与可持久化 HITL
- Linguagem predominante
- Java
- Estrelas
- 5.6k
- Forks
- 1.3k
- Merge médio
- 4d 12h
- PRs com merge (30d)
- 77
Descrição
## 背景
AgentScope Java 2.x 已有类型化 `AgentEvent` 流和一等 HITL 事件,但 A2A 模块仍依赖 1.0 之前的 Java SDK,并保留部分旧事件适配逻辑。#2222 已开始将 Server Runner 迁移到 `streamEvents`;本提案在此基础上补全 A2A 1.0 适配和远程 HITL 生命周期。
## 核心前提
将 A2A 模块从:
```text
io.github.a2asdk:*:0.3.3.Final
```
迁移到:
```text
org.a2aproject.sdk:*:1.0.0.Final
```
并将 protobuf runtime 对齐到 A2A 1.0 生成代码所需的 `4.33.2`。
这不是单纯的依赖版本升级:groupId、Java package 和 Server API 都发生变化。当前坐标改动集中在 dependency BOM 与 A2A client/server 模块。
## 方案范围
- 将 `AgentEvent` 映射为 A2A 1.0 artifact/status,包括 text、thinking、tool use/result、子 Agent source、input-required、failed、canceled 和 completed。
- Client 与 Server 使用独立状态机,保证终态 exactly-once,并明确处理缺失最终结果。
- 保持标准 A2A 互操作;AgentScope 的 block/source identity 仅作为可选 metadata,第三方 peer 按标准字段 best-effort 兼容。
- 为 user confirmation 与 external tool execution 增加可序列化 handoff、resume 和 cancel API。
- 在 SDK executor 调度前完成 resume admission,避免无效 token 或 response set 将原 Task 污染为 failed。
- HITL 默认关闭;提供 local 协调模式、durability SPI,以及可选的 Redisson 控制面参考实现。
- AgentStateStore 继续由应用负责,Redis provider 只管理 A2A Task、handoff、token claim、lease 和 TTL。
## 兼容性和边界
- AgentScope API 线:2.x。
- Wire protocol:A2A 1.0。
- 原有 `A2aAgent.call()` 保持可用,HITL API 为增量能力。
- 暂停会结束当前流,恢复是在相同 task/context 上的新请求。
- 不增加 in-task authentication 语义,因为 AgentScope 2.x 当前没有认证恢复契约。
- durable admission 可保证单次准入,但无法普遍保证任意崩溃点下外部副作用 exactly-once。
## 相关工作
- #2207:A2A 事件机制迁移。
- #2222:Server `streamEvents` 初始迁移;实现会保留原作者署名,并愿意按维护者意见拆分或 rebase。
- #2253:external-execution 事件缺口。
## 实现
完整实现和中英文文档已提交为 Draft PR #2311,便于维护者按模块评审或要求拆分。
Guia de contribuição
Avaliação
Esta issue ainda não foi avaliada.