feat(agent): support agent.stream for structuredModel (#161)

Author: zhangjiefan1992

agentscope-core/src/main/java/io/agentscope/core/agent/Agent.java

@@ -261,4 +261,30 @@ default Flux<Event> stream(Msg msg) {
     default Flux<Event> stream(List<Msg> msgs) {
         return stream(msgs, StreamOptions.defaults());
     }
+
+    /**
+     * Stream with default options (all event types except AGENT_RESULT, incremental mode).
+     *
+     * @param msg Input message
+     * @param options Stream configuration options
+     * @param structuredModel Optional class defining the structure
+     *
+     * @return Flux of events emitted during execution
+     */
+    Flux<Event> stream(Msg msg, StreamOptions options, Class<?> structuredModel);
+
+    /**
+     * Process multiple input messages with structured model and generate a response.
+     *
+     * <p>The structured model parameter defines the expected structure of input or output data.
+     * The structured data will be stored in the returned message's metadata field.
+     *
+     * <p>Default implementation ignores the structuredModel parameter. Agents that support
+     * structured input/output should override this method.
+     *
+     * @param msgs Input messages
+     * @param structuredModel Optional class defining the structure
+     * @return Response message with structured data in metadata
+     */
+    Flux<Event> stream(List<Msg> msgs, StreamOptions options, Class<?> structuredModel);
 }

agentscope-core/src/main/java/io/agentscope/core/agent/AgentBase.java

@@ -564,6 +564,19 @@ public final Flux<Event> stream(Msg msg, StreamOptions options) {
         return stream(List.of(msg), options);
     }
 
+    /**
+     * Stream execution events in real-time as the agent processes the input with structured output.
+     *
+     * @param msg Input message
+     * @param options Stream configuration options
+     * @param structuredModel Optional class defining the structure of the output
+     * @return Flux of events emitted during execution
+     */
+    @Override
+    public final Flux<Event> stream(Msg msg, StreamOptions options, Class<?> structuredModel) {
+        return stream(List.of(msg), options, structuredModel);
+    }
+
     /**
      * Stream with multiple input messages.
      *
@@ -576,6 +589,20 @@ public final Flux<Event> stream(List<Msg> msgs, StreamOptions options) {
         return createEventStream(options, () -> call(msgs));
     }
 
+    /**
+     * Stream with multiple input messages.
+     *
+     * @param msgs Input messages
+     * @param options Stream configuration options
+     * @param structuredModel Optional class defining the structure
+     * @return Flux of events emitted during execution
+     */
+    @Override
+    public final Flux<Event> stream(
+            List<Msg> msgs, StreamOptions options, Class<?> structuredModel) {
+        return createEventStream(options, () -> call(msgs, structuredModel));
+    }
+
     /**
      * Helper method to create an event stream with proper hook lifecycle management.
      *

agentscope-examples/quickstart/src/main/java/io/agentscope/examples/quickstart/StructuredOutputExample.java

@@ -16,6 +16,8 @@
 package io.agentscope.examples.quickstart;
 
 import io.agentscope.core.ReActAgent;
+import io.agentscope.core.agent.Event;
+import io.agentscope.core.agent.StreamOptions;
 import io.agentscope.core.formatter.dashscope.DashScopeChatFormatter;
 import io.agentscope.core.memory.InMemoryMemory;
 import io.agentscope.core.message.Msg;
@@ -24,6 +26,7 @@
 import io.agentscope.core.model.DashScopeChatModel;
 import io.agentscope.core.tool.Toolkit;
 import java.util.List;
+import reactor.core.publisher.Flux;
 
 /**
  * StructuredOutputExample - Demonstrates structured output generation.
@@ -71,6 +74,10 @@ public static void main(String[] args) throws Exception {
         System.out.println("\n=== Example 3: Sentiment Analysis ===\n");
         runSentimentAnalysisExample(agent);
 
+        // Example 4: Extract product information by Stream
+        System.out.println("=== Example 4: Product Information ===\n");
+        runStreamProductAnalysisExample(agent);
+
         System.out.println("\n=== All examples completed ===");
     }
 
@@ -186,6 +193,46 @@ private static void runSentimentAnalysisExample(ReActAgent agent) {
         }
     }
 
+    /** Example 4: Extract product information from natural language description. */
+    private static void runStreamProductAnalysisExample(ReActAgent agent) {
+        String query =
+                "I'm looking for a laptop. I need at least 16GB RAM, "
+                        + "prefer Apple brand, and my budget is around $2000. "
+                        + "It should be lightweight for travel.";
+
+        System.out.println("Query: " + query);
+        System.out.println("\nRequesting structured output...\n");
+
+        Msg userMsg =
+                Msg.builder()
+                        .role(MsgRole.USER)
+                        .content(
+                                TextBlock.builder()
+                                        .text(
+                                                "Extract the product requirements from this query: "
+                                                        + query)
+                                        .build())
+                        .build();
+
+        try {
+            Flux<Event> eventFlux =
+                    agent.stream(userMsg, StreamOptions.defaults(), ProductRequirements.class);
+            ProductRequirements result =
+                    eventFlux.blockLast().getMessage().getStructuredData(ProductRequirements.class);
+
+            System.out.println("Extracted structured data:");
+            System.out.println("  Product Type: " + result.productType);
+            System.out.println("  Brand: " + result.brand);
+            System.out.println("  Min RAM: " + result.minRam + " GB");
+            System.out.println("  Max Budget: $" + result.maxBudget);
+            System.out.println("  Features: " + result.features);
+
+        } catch (Exception e) {
+            System.err.println("Error: " + e.getMessage());
+            e.printStackTrace();
+        }
+    }
+
     // ==================== Structured Output Schema Classes ====================
 
     /** Schema for product requirements extraction. */