feat: support agent.stream for structuredModel

[zhangjiefan1992]

AgentScope-Java Version

1.0.2-SNAPSHOT

Description

Background

This PR extends the AgentScope-Java framework to support structured output generation in streaming mode. Previously, the stream() methods only supported basic message streaming without structured output capabilities, limiting the flexibility for applications that need both real-time streaming and structured data extraction.

Purpose

Enable agents to generate structured output while streaming execution events, providing developers with the ability to:

• Stream agent execution events in real-time
• Extract structured data from the final result
• Maintain type safety with structured output schemas
• Support both single message and multiple message inputs with structured models

Changes Made

1. Core Interface Extensions (Agent.java)

• Added stream(Msg msg, StreamOptions options, Class<?> structuredModel) method
• Added stream(List<Msg> msgs, StreamOptions options, Class<?> structuredModel) method
• Added convenience method stream(Class<?> structuredModel) for continuation with structured output
• Enhanced Javadoc documentation with detailed usage examples and parameter descriptions

2. Base Implementation (AgentBase.java)

• Implemented stream() methods with structured model support in the abstract base class
• Added call(List<Msg> msgs, Class<?> structuredOutputClass) method with proper hook integration
• Enhanced doCall(List<Msg> msgs, Class<?> structuredOutputClass) abstract method for subclass implementation
• Maintained thread safety and interrupt handling for structured streaming operations

3. Example Enhancement (StructuredOutputExample.java)

• Added runStreamProductAnalysisExample() method demonstrating structured streaming usage
• Shows practical implementation of agent.stream(msg, StreamOptions.defaults(), ProductRequirements.class)
• Demonstrates extraction of structured data from streamed events using event.getMessage().getStructuredData()

How to Test This PR

Prerequisites:

• DashScope API key configured
• Java 17+ environment

Test Steps:

1. Run the enhanced example:

   cd agentscope-examples/quickstart
   mvn exec:java -Dexec.mainClass="io.agentscope.examples.quickstart.StructuredOutputExample"

2. Verify streaming with structured output:

   • Observe real-time event streaming in Example 4
   • Confirm structured data extraction from final event
   • Compare results with non-streaming Example 1

3. Integration testing:

   • Test with different structured model classes (ProductRequirements, ContactInfo, SentimentAnalysis)
   • Verify error handling for unsupported agents
   • Test interrupt functionality during structured streaming

4. API compatibility:

   • Ensure existing stream() methods continue to work
   • Verify backward compatibility with non-structured streaming
   • Test default method implementations

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)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

---

Summary: This PR adds structured output support to the streaming API, enabling developers to combine real-time event streaming with type-safe structured data extraction. The implementation maintains full backward compatibility while extending the framework's capabilities for advanced use cases.

[cla-assistant]

All committers have signed the CLA.

[AlbumenJ]

pls fix ci

[AlbumenJ]

Please fix ci

[codecov]

Codecov Report

❌ Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../main/java/io/agentscope/core/agent/AgentBase.java	0.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!