refactor(agui): redesign event dispatching with strategy pattern and deferred queue

[jujn]

Description:
Closes #1347, #1222, #1382

This PR implements the architectural refactoring proposed in Issue 1347, bringing a strategy-based dispatcher to the AG-UI adapter and enabling pluggable custom converters. Additionally, it introduces support for real-time tool execution progress events (#1222) and seamlessly fixes the lifecycle mismatch bug mentioned in #1382.

Code Changes & Architecture

1. Refactored AguiAgentAdapter: Replaced the massive if-else block with a BlockEventConverter strategy interface. The adapter now acts as a clean router (O(1) dispatching based on Block class).
2. Introduced StreamContext: Replaced the heavy Set-based state tracking with a lightweight context. It uses a Deferred Queue mechanism (delaying End events until termination or interruption), resolving lifecycle mismatch bugs.
3. Added BlockEventConverter Implementations: Logic for TextBlock, ThinkingBlock, ToolUseBlock, and ToolResultBlock are now beautifully isolated in their own classes.
4. Introduced Pluggable customConverters & enableActingChunk: To support [Feature]: [功能建议] AGUI 中支持长时间运行的工具实时反馈执行情况 #1222 and future broader customization needs without modifying the core framework, we introduced new configuration mechanisms:
   • Core Config (AguiAdapterConfig): Added customConverters to allow developers to register their own BlockEventConverter implementations, and enableActingChunk to control the emission of intermediate execution chunks.
   • Spring Boot Auto-Configuration (agui-spring-boot-starter): Updated AguiProperties to include enable-acting-chunk. Modified AgentscopeAguiMvcAutoConfiguration and AgentscopeAguiWebFluxAutoConfiguration by utilizing ObjectProvider<BlockEventConverter<?>>. This allows the framework to automatically collect any custom converter beans defined in the Spring context (e.g., using @Component), transforming the adapter into a highly extensible microkernel architecture.
5. Updated AG-UI Examples: Modified the ag-ui examples project to demonstrate how to implement and correctly display real-time tool progress in the frontend.
6. Updated Documentation & Tests: Add documentation introduction for the ag-ui sample project. For AguiAgentAdapterTest.java, all existing unit tests pass smoothly(just modified one), proving backward compatibility. And added new tests to cover the remaining newly added code.

[📝 Multi-Model Log Comparison]

To ensure that the refactored AguiAgentAdapter behaves consistently and correctly across different LLMs, I evaluated the AG-UI event outputs before and after the refactoring by running 12 test cases(See the attachment agui_test.js) across each of the 5 different models (qwen3.5-plus, gpt-5.2, kimi-k2.6, MiniMax-M2.5, deepseek-v4-pro, glm-5).

Testing context: The tests were conducted using agentscope-examples/integration/agui with reasoning events enabled. (Test scripts and full logs are attached).
Result: After a rigorous dual review by human and AI, the results show zero issues post-refactoring.

Appendix: AG-UI Log Review Criteria
The logs were meticulously audited against the following standards:

1. Lifecycle Completeness: Ensure the complete lifecycle (start, content, end) for reasoning events, tool call events, and text events (tool calls also include a result event). The messageId or toolCallId must remain exactly consistent throughout each lifecycle.
2. Strict Event Ordering: Ensure events follow a rigorous sequence (e.g., a reasoning event must fully end before a text event starts; a reasoning event must fully end before a tool event starts).
3. No Duplicate Events: Check for redundant start or end events within each test case (e.g., no multiple reasoning start/end events sharing the identical messageId).
4. Content Integrity: Verify that concatenated content events form a complete message without any truncation or interruption.
5. Focus: Note that the "before" logs may contain pre-existing framework bugs. The primary focus of this audit is verifying the absolute correctness of the "after" logs (post-refactoring).

测试脚本及日志.zip

[Copilot]

Pull request overview

This PR refactors the AG-UI adapter’s streaming event conversion to use a strategy-based dispatch model with a dedicated StreamContext that supports deferred “end” events, and extends the core message model with a CustomBlock to enable emitting AG-UI CUSTOM events.

Changes:

• Refactors AguiAgentAdapter to dispatch ContentBlock conversion via BlockEventConverter strategies and manage lifecycle/end-event ordering via StreamContext.
• Adds block converters for text, thinking/reasoning, tool use/results, and custom blocks under adapter.strategy.
• Introduces CustomBlock as a new ContentBlock subtype and wires it into Jackson polymorphic serialization; updates AG-UI adapter tests for revised lifecycle behavior.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/AguiAgentAdapter.java	Refactors the adapter to strategy-based block conversion and deferred end-event flushing.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/StreamContext.java	Adds a context object to track active lifecycles and queue/flush deferred end events.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/BlockEventConverter.java	Introduces the strategy interface for block→event conversion.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/TextBlockConverter.java	Implements text block conversion with lifecycle tracking and deferred end events.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/ThinkingBlockConverter.java	Implements reasoning conversion (when enabled) with lifecycle tracking and deferred end events.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/ToolUseBlockConverter.java	Implements tool call start/args conversion and interrupts active text/reasoning lifecycles.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/ToolResultBlockConverter.java	Implements tool result conversion and ensures tool call closure semantics.
agentscope-extensions/agentscope-extensions-agui/src/main/java/io/agentscope/core/agui/adapter/strategy/CustomBlockConverter.java	Implements CustomBlock→AG-UI CUSTOM event emission.
agentscope-extensions/agentscope-extensions-agui/src/test/java/io/agentscope/core/agui/adapter/AguiAgentAdapterTest.java	Updates test expectations for the new lifecycle/event ordering behavior.
agentscope-core/src/main/java/io/agentscope/core/message/CustomBlock.java	Adds a new ContentBlock subtype for custom extension payloads.
agentscope-core/src/main/java/io/agentscope/core/message/ContentBlock.java	Registers CustomBlock in the sealed hierarchy and Jackson subtype mapping.

[codecov]

Codecov Report

❌ Patch coverage is 80.35714% with 44 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...t/agui/mvc/AgentscopeAguiMvcAutoConfiguration.java	0.00%	9 Missing ⚠️
...ebflux/AgentscopeAguiWebFluxAutoConfiguration.java	0.00%	9 Missing ⚠️
...gui/adapter/strategy/ToolResultBlockConverter.java	81.25%	0 Missing and 6 partials ⚠️
...core/agui/adapter/strategy/TextBlockConverter.java	82.60%	0 Missing and 4 partials ⚠️
.../agui/adapter/strategy/ThinkingBlockConverter.java	84.00%	0 Missing and 4 partials ⚠️
...tscope/spring/boot/agui/common/AguiProperties.java	0.00%	4 Missing ⚠️
...e/agui/adapter/strategy/ToolUseBlockConverter.java	86.95%	0 Missing and 3 partials ⚠️
...gentscope/core/agui/adapter/AguiAdapterConfig.java	85.71%	0 Missing and 2 partials ⚠️
...agentscope/core/agui/adapter/AguiAgentAdapter.java	92.59%	0 Missing and 2 partials ⚠️
...io/agentscope/core/agui/adapter/StreamContext.java	98.27%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!