agentscope-ai / agentscope-ai/agentscope-java

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

未關閉
#2,270 1 則留言 2 個 reaction 已指派 0 人 在 GitHub 檢視
area/ext/integration enhancement
主要語言
Java
星號
5.6k
分支
1.3k
平均合併
4 天 12 小時
30 天內合併 PR
77

描述

## 背景

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,便于维护者按模块评审或要求拆分。

貢獻指南

開啟貢獻指南

評估

這個 Issue 還沒有評估資料。

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

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