feat(middleware): add final answer filter for ReAct streams

agentscope-core/src/main/java/io/agentscope/core/middleware/FinalAnswerFilterMiddleware.java

@@ -0,0 +1,140 @@
+/*
+ * Copyright 2024-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.agentscope.core.middleware;
+
+import io.agentscope.core.agent.Agent;
+import io.agentscope.core.agent.RuntimeContext;
+import io.agentscope.core.event.AgentEvent;
+import io.agentscope.core.event.ModelCallEndEvent;
+import io.agentscope.core.event.ModelCallStartEvent;
+import io.agentscope.core.event.TextBlockDeltaEvent;
+import io.agentscope.core.event.TextBlockEndEvent;
+import io.agentscope.core.event.TextBlockStartEvent;
+import io.agentscope.core.event.ToolCallStartEvent;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Function;
+import reactor.core.publisher.Flux;
+
+/**
+ * Exposes only the text from the final reasoning round of a ReAct stream.
+ *
+ * <p>Text events are buffered until the current model call completes. If the model produces a
+ * tool call during that round, the buffered and subsequent text events are suppressed. Otherwise,
+ * the buffered text events are emitted before the corresponding {@link ModelCallEndEvent}.
+ *
+ * <p>This middleware is opt-in and does not change the default behavior of {@code ReActAgent}.
+ * Because a round can only be identified as intermediate after a tool call is observed, text from
+ * the current round is not emitted until the model call completes or a tool call is detected.
+ */
+public class FinalAnswerFilterMiddleware implements MiddlewareBase {
+
+    @Override
+    public Flux<AgentEvent> onReasoning(
+            Agent agent,
+            RuntimeContext ctx,
+            ReasoningInput input,
+            Function<ReasoningInput, Flux<AgentEvent>> next) {
+        return Flux.defer(
+                () -> {
+                    RoundState state = new RoundState();
+                    return next.apply(input)
+                            .concatMap(state::handle)
+                            .doFinally(signal -> state.clear());
+                });
+    }
+
+    private static boolean isTextBlockEvent(AgentEvent event) {
+        return event instanceof TextBlockStartEvent
+                || event instanceof TextBlockDeltaEvent
+                || event instanceof TextBlockEndEvent;
+    }
+
+    private static final class RoundState {
+        private final List<AgentEvent> bufferedTextEvents = new ArrayList<>();
+        private String replyId;
+        private boolean toolCallSeen;
+
+        private Flux<AgentEvent> handle(AgentEvent event) {
+            if (event instanceof ModelCallStartEvent start) {
+                replyId = start.getReplyId();
+                toolCallSeen = false;
+                bufferedTextEvents.clear();
+                return Flux.just(event);
+            }
+
+            if (isTextBlockEvent(event)) {
+                if (isCurrentReply(event) && !toolCallSeen) {
+                    bufferedTextEvents.add(event);
+                    return Flux.empty();
+                }
+                if (isCurrentReply(event)) {
+                    return Flux.empty();
+                }
+                return Flux.just(event);
+            }
+
+            if (event instanceof ToolCallStartEvent toolCall
+                    && Objects.equals(replyId, toolCall.getReplyId())) {
+                toolCallSeen = true;
+                bufferedTextEvents.clear();
+                return Flux.just(event);
+            }
+
+            if (event instanceof ModelCallEndEvent end && isCurrentReply(end)) {
+                if (toolCallSeen) {
+                    clear();
+                    return Flux.just(event);
+                }
+
+                List<AgentEvent> finalEvents = new ArrayList<>(bufferedTextEvents);
+                finalEvents.add(event);
+                clear();
+                return Flux.fromIterable(finalEvents);
+            }
+
+            return Flux.just(event);
+        }
+
+        private boolean isCurrentReply(AgentEvent event) {
+            String eventReplyId = getReplyId(event);
+            return replyId != null && Objects.equals(replyId, eventReplyId);
+        }
+
+        private static String getReplyId(AgentEvent event) {
+            if (event instanceof TextBlockStartEvent textStart) {
+                return textStart.getReplyId();
+            }
+            if (event instanceof TextBlockDeltaEvent textDelta) {
+                return textDelta.getReplyId();
+            }
+            if (event instanceof TextBlockEndEvent textEnd) {
+                return textEnd.getReplyId();
+            }
+            if (event instanceof ModelCallEndEvent modelEnd) {
+                return modelEnd.getReplyId();
+            }
+            return null;
+        }
+
+        private void clear() {
+            bufferedTextEvents.clear();
+            replyId = null;
+            toolCallSeen = false;
+        }
+    }
+}

agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentMiddlewareIntegrationTest.java

@@ -26,26 +26,37 @@
 import io.agentscope.core.event.AgentEvent;
 import io.agentscope.core.event.AgentStartEvent;
 import io.agentscope.core.event.HintBlockEvent;
+import io.agentscope.core.event.ModelCallEndEvent;
 import io.agentscope.core.event.ModelCallStartEvent;
 import io.agentscope.core.event.TextBlockDeltaEvent;
+import io.agentscope.core.event.ToolCallStartEvent;
 import io.agentscope.core.message.ContentBlock;
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.message.TextBlock;
+import io.agentscope.core.message.ToolResultBlock;
+import io.agentscope.core.message.ToolUseBlock;
 import io.agentscope.core.middleware.ActingInput;
 import io.agentscope.core.middleware.AgentInput;
+import io.agentscope.core.middleware.FinalAnswerFilterMiddleware;
 import io.agentscope.core.middleware.MiddlewareBase;
 import io.agentscope.core.middleware.ModelCallInput;
 import io.agentscope.core.middleware.ReasoningInput;
 import io.agentscope.core.model.ChatModelBase;
 import io.agentscope.core.model.ChatResponse;
 import io.agentscope.core.model.GenerateOptions;
 import io.agentscope.core.model.ToolSchema;
+import io.agentscope.core.permission.PermissionContextState;
+import io.agentscope.core.permission.PermissionDecision;
 import io.agentscope.core.state.AgentState;
+import io.agentscope.core.tool.ToolBase;
+import io.agentscope.core.tool.ToolCallParam;
 import io.agentscope.core.tool.Toolkit;
 import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import java.util.concurrent.CopyOnWriteArrayList;
+import java.util.concurrent.atomic.AtomicInteger;
 import java.util.function.Function;
 import org.junit.jupiter.api.Test;
 import reactor.core.publisher.Flux;
@@ -80,6 +91,71 @@ protected Flux<ChatResponse> doStream(
         }
     }
 
+    private static final class ToolThenFinalModel extends ChatModelBase {
+        private final AtomicInteger calls = new AtomicInteger();
+
+        @Override
+        public String getModelName() {
+            return "tool-then-final";
+        }
+
+        @Override
+        protected Flux<ChatResponse> doStream(
+                List<Msg> messages, List<ToolSchema> tools, GenerateOptions options) {
+            if (calls.getAndIncrement() == 0) {
+                return Flux.just(
+                        ChatResponse.builder()
+                                .content(
+                                        List.of(
+                                                TextBlock.builder()
+                                                        .text("intermediate text")
+                                                        .build(),
+                                                ToolUseBlock.builder()
+                                                        .id("tool-call-1")
+                                                        .name("lookup")
+                                                        .input(Map.of("query", "AgentScope"))
+                                                        .build()))
+                                .build());
+            }
+            return Flux.just(
+                    ChatResponse.builder()
+                            .content(
+                                    List.<ContentBlock>of(
+                                            TextBlock.builder().text("final answer").build()))
+                            .build());
+        }
+    }
+
+    private static final class LookupTool extends ToolBase {
+        LookupTool() {
+            super(
+                    "lookup",
+                    "Looks up a query",
+                    Map.of(
+                            "type",
+                            "object",
+                            "properties",
+                            Map.of("query", Map.of("type", "string"))),
+                    true,
+                    true,
+                    false,
+                    null,
+                    false,
+                    false);
+        }
+
+        @Override
+        public Mono<PermissionDecision> checkPermissions(
+                Map<String, Object> input, PermissionContextState ctx) {
+            return Mono.just(PermissionDecision.allow("allowed"));
+        }
+
+        @Override
+        public Mono<ToolResultBlock> callAsync(ToolCallParam param) {
+            return Mono.just(ToolResultBlock.text("lookup result"));
+        }
+    }
+
     private static final class InterruptedAfterTextModel extends ChatModelBase {
         @Override
         public String getModelName() {
@@ -167,6 +243,35 @@ private static ReActAgent buildAgent(ChatModelBase model, List<MiddlewareBase> m
                 .build();
     }
 
+    @Test
+    void finalAnswerFilterSuppressesIntermediateReactRoundText() {
+        ToolThenFinalModel model = new ToolThenFinalModel();
+        Toolkit toolkit = new Toolkit();
+        toolkit.registerAgentTool(new LookupTool());
+        ReActAgent agent =
+                ReActAgent.builder()
+                        .name("asst")
+                        .sysPrompt("hello-system")
+                        .model(model)
+                        .toolkit(toolkit)
+                        .middleware(new FinalAnswerFilterMiddleware())
+                        .build();
+
+        List<AgentEvent> events = agent.streamEvents(List.of()).collectList().block();
+
+        assertNotNull(events);
+        assertEquals(2, model.calls.get());
+        assertEquals(
+                List.of("final answer"),
+                events.stream()
+                        .filter(TextBlockDeltaEvent.class::isInstance)
+                        .map(TextBlockDeltaEvent.class::cast)
+                        .map(TextBlockDeltaEvent::getDelta)
+                        .toList());
+        assertEquals(2L, events.stream().filter(ModelCallEndEvent.class::isInstance).count());
+        assertTrue(events.stream().anyMatch(ToolCallStartEvent.class::isInstance));
+    }
+
     @Test
     void singleMiddlewareSeesReplyAndReasoningAndModelCall() {
         List<String> trace = new ArrayList<>();