feat(core): add EventStreamingAgent so AG-UI can adapt custom agents

[dragondyt]

AgentScope-Java Version

2.0.3-SNAPSHOT

Description

Closes #1894
Related #2102 #2105 #2552

Background

AguiAgentAdapter used to hard-code ReActAgent and HarnessAgent to reach the v2 streamEvents path. Those types are not suitable as a shared base class, so custom agents (including graph-based and A2A agents) could only fall back to the 1.x stream() conversion and lost fine-grained AG-UI events.

Purpose

Extract the v2 streaming contract into an optional EventStreamingAgent interface so protocol adapters can adapt any implementing agent without knowing the concrete type.

Changes

• Add EventStreamingAgent with streamEvents(List<Msg>, RuntimeContext) and default overloads.
• Implement the interface on ReActAgent and HarnessAgent.
• Route AguiAgentAdapter through instanceof EventStreamingAgent and remove the ReActAgent / Harness reflection hard-coding. Generic Agent implementations still use the 1.x stream() fallback.
• Point the deprecated StreamableAgent documentation at EventStreamingAgent.

How to test / Test plan

All items below were executed locally and passed:

• EventStreamingAgentTest
• HarnessAgentEventStreamingContractTest
• AguiAgentAdapterV2Test (ReAct / Harness / custom EventStreamingAgent path)
• AguiAgentAdapterTest (v1 stream() fallback)
• StreamableAgentTest
• AguiUtilTest
• mvn spotless:apply on the affected modules (agentscope-core, agentscope-harness, agentscope-extensions-agui)

mvn -pl agentscope-core -Dtest=EventStreamingAgentTest,StreamableAgentTest test
mvn -pl agentscope-harness -Dtest=HarnessAgentEventStreamingContractTest test
mvn -pl agentscope-extensions/agentscope-extensions-protocol/agentscope-extensions-agui -Dtest=AguiAgentAdapterV2Test,AguiAgentAdapterTest,AguiUtilTest test

Full-repo mvn test is left to CI.

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test) — affected tests listed above; full suite in CI
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.) — Agent / StreamableAgent Javadoc
• Code is ready for review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[oss-maintainer]

Summary

Extracts the v2 streaming contract into a new EventStreamingAgent SPI, implements it on ReActAgent/HarnessAgent, and drops the ReActAgent cast plus the reflective HarnessAgent call from AguiAgentAdapter. Nice de-escalation of a hard-coded type check into a proper capability interface, with tests for the ReAct / Harness / custom-agent paths and the v1 fallback.

Verdict

Approachable with one compatibility question answered (see inline): agents that used to reach the v2 path by class name alone now fall back to 1.x silently.

---

Automated review by github-manager-bot