AG-UI adapter drops human-in-the-loop tool confirmation (consumes deprecated v1 Event stream; RequireUserConfirmEvent never bridged)

[wzq-xzwj]

Summary

The AG-UI adapter (AguiAgentAdapter) consumes the deprecated v1 Flux<io.agentscope.core.agent.Event> stream via agent.stream(...). Because the v1 Event/EventType vocabulary only contains REASONING / SUMMARY / TOOL_RESULT, the fine-grained v2 events — in particular RequireUserConfirmEvent and RequestStopEvent — structurally can never reach the adapter.

As a result, human-in-the-loop (HITL) tool confirmation is completely dropped over AG-UI:

• When a tool call enters ToolCallState.ASKING (e.g. any non-read-only tool under PermissionMode.DEFAULT, which is the default), ReActAgent emits RequireUserConfirmEvent + RequestStopEvent and pauses.
• Neither event is converted to any AG-UI event, so the client sees TOOL_CALL_START/ARGS/END and then a bare RUN_FINISHED (or a RUN_ERROR on a subsequent run whose paused state was persisted) — the tool call silently never executes.
• There is also no inbound path: AguiRequestProcessor / RunAgentInput / AguiMessageConverter never read confirmation results back, so even a client that wanted to approve/deny has no channel to send ConfirmResult (Msg metadata key agentscope_confirm_results).

This is especially visible with MCP tools: the MCP server receives initialize and tools/list but never receives tools/call, because the agent halts at the ASKING gate before ToolExecutor runs.

Environment

• agentscope-java: 2.0.0
• Module: agentscope-extensions/agentscope-extensions-protocol/agentscope-extensions-agui
• Transport: AG-UI over SSE (agentscope-agui-spring-boot-starter, MVC SseEmitter)

Root cause (verified against main)

1. The adapter is on the deprecated v1 event stream.

AguiAgentAdapter.run(RunAgentInput) calls:

// AguiAgentAdapter.java
Flux<Event> agentEvents = agent.stream(msgs, options, runtimeContext); // io.agentscope.core.agent.Event (v1)
...
agentEvents.concatMapIterable(event -> convertEvent(event, state));

and convertEvent(Event, ...) only branches on EventType.REASONING | SUMMARY | TOOL_RESULT. The entire StreamableAgent surface is already marked for removal:

// StreamableAgent.java
 * @deprecated since 2.0.0, for removal in a future minor release. Every stream(...)
 *     method returns the coarse-grained Event type (a v1 carry-over). Use
 *     ReActAgent#streamEvents(...) instead — it returns Flux<io.agentscope.core.event.AgentEvent>,
 *     the fine-grained event hierarchy ...
@Deprecated(since = "2.0.0", forRemoval = true)
public interface StreamableAgent { ... }

The v1 Event.java deprecation javadoc even names AG-UI explicitly as a module still on the old wire format:

 * @deprecated since 2.0.0. This is the v1 coarse-grained event type ... the wire format
 *     consumed by the harness, AGUI, A2A, chat-completions-web, and Kotlin extension modules.
 *     New code should use io.agentscope.core.event.AgentEvent via ReActAgent#streamEvents(...).

2. The two event hierarchies are disjoint and there is no bridge.

io.agentscope.core.agent.Event (v1, a flat class wrapping Msg + coarse EventType) and io.agentscope.core.event.AgentEvent (v2 abstract base with 28 typed subtypes and its own AgentEventType) are in different packages, unrelated by inheritance. There is no in-core converter from AgentEvent down to v1 Event. So RequireUserConfirmEvent cannot be observed from the stream the adapter currently subscribes to — a "small patch inside the v1 adapter" is not possible.

3. The AG-UI layer already defines the target types but never constructs them.

AguiEvent.java defines Interrupt, RunFinishedOutcome, RunFinishedSuccessOutcome, and RunFinishedInterruptOutcome(List<Interrupt>) — the Interrupt javadoc reads "requiring user input to resolve before the agent can continue" — but no production code ever instantiates them. finishRun(...) always emits the bare new AguiEvent.RunFinished(threadId, runId) (outcome = null). The interrupt types are exercised only in AguiEventTest (serialization).

Reproduction

1. Register any HarnessAgent/ReActAgent with default permissions (PermissionMode.DEFAULT) behind the AG-UI Spring Boot starter.
2. Configure any non-read-only tool (e.g. an MCP echo tool via tools.json).
3. POST /agui/run asking the model to call that tool.

Observed: SSE stream shows RUN_STARTED → TEXT_* → TOOL_CALL_START/ARGS/END → RUN_FINISHED, with no TOOL_CALL_RESULT and no confirmation event. Server-side, the agent stops at PRE_ACTING with RequestStopEvent(reason=permission asking) and ToolExecutor never runs; an MCP server never receives tools/call.

Expected: the confirmation request should surface to the client (as an AG-UI Interrupt / RunFinishedInterruptOutcome, or another agreed representation), and the client should be able to resume the run by sending approval/denial that is translated back into ConfirmResult (Msg metadata agentscope_confirm_results).

Workaround today: set PermissionMode.BYPASS (or add explicit allow rules) on the agent's PermissionContextState, which skips the ASK gate entirely. This unblocks tool execution but discards the HITL capability that AG-UI otherwise seems designed to support.

Reference for the intended v2 pattern

The canonical dispatch + resume flow already exists in tests:

• agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentHitlTest.java — subscribes to streamEvents(...), dispatches via instanceof over RequireUserConfirmEvent / RequestStopEvent (GenerateReason.PERMISSION_ASKING), extracts pending ToolUseBlocks via getToolCalls(), and resumes with new ConfirmResult(approved, toolCall).
• agentscope-harness/src/test/java/io/agentscope/harness/agent/HarnessAgentSubagentStreamEventsTest.java — subscribes to streamEvents(...) and dispatches by AgentEventType.

Suggested direction

Migrate AguiAgentAdapter from the deprecated agent.stream(...) (Flux<Event>) to ReActAgent#streamEvents(...) (Flux<AgentEvent>), rewrite convertEvent to dispatch over the typed v2 events (TEXT_BLOCK_*, THINKING_BLOCK_*, TOOL_CALL_*, TOOL_RESULT_*), and add HITL handling that maps RequireUserConfirmEvent → AguiEvent.Interrupt (+ RunFinishedInterruptOutcome) outbound, plus an inbound path that reads confirmation results from the incoming RunAgentInput and forwards them as ConfirmResult (Msg.METADATA_CONFIRM_RESULTS).

Note: streamEvents is declared on ReActAgent, not on the Agent interface, so the adapter would need to target ReActAgent (or a narrower event-streaming type) — worth deciding as part of the fix.

I'm happy to work on a PR for this.

---

_{Note: HITL confirmation over AG-UI is currently non-functional; the adapter being on the forRemoval v1 stream is the underlying cause. This is a defensive/UX correctness issue rather than a data-loss bug.}

[oss-maintainer]

Thanks for this thorough analysis.

Classification: Bug — AG-UI adapter drops human-in-the-loop (HITL) tool confirmation events.

Root cause: The AguiAgentAdapter consumes the deprecated v1 Flux<Event> stream, which only contains REASONING / SUMMARY / TOOL_RESULT event types. The v2 fine-grained events — specifically RequireUserConfirmEvent and RequestStopEvent — structurally cannot reach the adapter through this path.

Impact: HITL tool confirmation is completely non-functional over the AG-UI protocol. Users cannot review or approve tool invocations when using the AG-UI adapter.

Assessment: This is a legitimate bug. The adapter needs to be migrated to the v2 event stream to properly bridge RequireUserConfirmEvent and RequestStopEvent.

Severity: Medium-High — breaks a critical safety feature (human-in-the-loop confirmation).

Suggested fix direction:

1. Migrate AguiAgentAdapter from agent.stream(...) (v1) to the v2 event API
2. Add explicit bridging for RequireUserConfirmEvent → AG-UI confirmation protocol
3. Add bridging for RequestStopEvent → AG-UI stop signal

No existing PR addresses this issue yet. Maintainers, please prioritize.

/cc @maintainers

[wzq-xzwj]

I'd like to take this one. I've already done the root-cause analysis above and have a working local branch.

Plan (single PR, closes this issue):

1. Migrate AguiAgentAdapter to the v2 AgentEvent stream. When the wrapped agent is a ReActAgent, consume streamEvents(msgs, ctx) (Flux<AgentEvent>) and map the fine-grained events onto the AG-UI protocol:

   • TextBlock{Start,Delta,End}Event → TEXT_MESSAGE_{START,CONTENT,END}
   • ThinkingBlock{Start,Delta,End}Event → REASONING_MESSAGE_* (when enableReasoning)
   • ToolCall{Start,Delta,End}Event → TOOL_CALL_{START,ARGS,END}
   • ToolResult{Start,TextDelta,End}Event → TOOL_CALL_RESULT
   • For any non-ReActAgent, keep the existing deprecated v1 stream(...) path as a fallback, so custom Agent implementations and current integrations keep working.

2. Bridge HITL outbound. RequireUserConfirmEvent (+ RequestStopEvent with GenerateReason.PERMISSION_ASKING) → emit an AguiEvent.Interrupt carrying the pending ToolUseBlocks, and finish the run with RunFinishedInterruptOutcome instead of a bare RUN_FINISHED.

3. Bridge HITL inbound. Read confirmation results from RunAgentInput.forwardedProps, translate to List<ConfirmResult>, and attach them under Msg.METADATA_CONFIRM_RESULTS on the resumed message so ReActAgent can apply them and continue.

Testing:

• Unit tests for the v2 mapping (text / reasoning / tool-call / tool-result ordering) and for the HITL round-trip (outbound Interrupt + inbound ConfirmResult resume).
• End-to-end verification against a local DeepSeek + SSE MCP demo: confirm the interrupt reaches the client and a confirmation resumes the run.

Will open the PR against main shortly. Please assign to me / let me know if the approach looks good.

[jujn]

先等这个合并吧，不然后面大概率冲突： #2306

[wzq-xzwj]

Update: @jujn pointed out that #2306 (already approved and mergeable) covers this issue — it migrates the AG-UI adapter from the v1 stream() to the v2 streamEvents() API and bridges HITL through the official RunAgentInput.resume[] contract.

I've closed my PR (#2473) in favor of #2306 to avoid conflicts. Happy to re-verify against my local DeepSeek + SSE MCP setup once #2306 lands, and will reopen/complement only if any gap remains. Thanks @jujn for the heads-up!

[wzq-xzwj]

做了一个端到端验证，确认目前 #2437 描述的权限型 HITL 场景仍需要补充处理。

#2306 对 suspend 型 HITL（TOOL_SUSPENDED 路径）的 converter registry + interrupt coordinator 架构很完善。但 #2437 是另一条独立分支——PermissionMode.DEFAULT 下非只读工具触发 RequireUserConfirmEvent + RequestStopEvent(PERMISSION_ASKING)，在适配器里还没有对应的 converter。

实测（合并后 main @6572a3e，非只读 MCP echo 工具，PermissionMode.DEFAULT，真实模型）：

TOOL_CALL_START (echo) → TOOL_CALL_END
RAW  { type: REQUIRE_USER_CONFIRM, toolCalls: [{state: "pending"}] }   ← 降级为 RAW
RAW  { type: REQUEST_STOP, generateReason: PERMISSION_ASKING }          ← 降级为 RAW
RUN_FINISHED   ← 没有 interrupt outcome

MCP server 收到 tools/call = 0（权限 ASK 正确拦截了执行）。但 RequireUserConfirmEvent 只被 RawAgentEventConverter 兜底转发为不透明的 RAW，适配器没有产出 Interrupt，客户端无法确认/续跑。

根因： 目前唯一的中断源是 AgentLifecycleEventConverter（gated on GenerateReason.TOOL_SUSPENDED）。RequireUserConfirmEvent 在整个 agui 模块没有 handler。ReActAgent 里 PERMISSION_ASKING 和 TOOL_SUSPENDED 是两条互斥分支，当前只覆盖了后者。

补充方案（基于 #2306 的 registry 架构）：

1. 新增 PermissionConfirmEventConverter（实现 AgentEventConverter，eventTypes = Set.of(RequireUserConfirmEvent.class)），将 RequireUserConfirmEvent 转为 context.addInterrupt(new Interrupt(id, reason="tool_confirmation", ...))，每个 pending ToolUseBlock 一个 Interrupt，metadata 携带 toolName/toolInput。

2. 扩展 AguiResumeCoordinator 和 AguiMessageConverter，对 reason="tool_confirmation" 的中断走不同的 resume 路径：构造携带 Msg.METADATA_CONFIRM_RESULTS（List<ConfirmResult>）的 USER role 消息，而不是现有的 ToolResultBlock 路径。

3. 注意： ConfirmResult.toolCall 的 content 必须是非空 JSON——applyConfirmResults 是全量替换 stored ToolUseBlock，如果 content 为 null 会在 resume 时触发 "argument content is null" 校验失败。

如果方向 OK 我可以提一个 PR。