Merge branch 'main' into fix/951-react-agent-tool-execution-error-handling

Author: chensk0601

.github/workflows/close-stale-prs.yml

@@ -0,0 +1,24 @@
+name: "Close stale PRs"
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch: 
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/stale@v9
+        with:
+          only-labels: 'wait-for-response'
+          days-before-stale: 7
+          days-before-close: 0
+          stale-pr-message: >
+            Closing due to inactivity. Feel free to reopen when ready.
+          stale-pr-label: 'stale'
+          days-before-issue-stale: -1
+          days-before-issue-close: -1

agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java

@@ -138,6 +138,7 @@ public class ReActAgent extends StructuredOutputCapableAgent {
     private final int maxIters;
     private final ExecutionConfig modelExecutionConfig;
     private final ExecutionConfig toolExecutionConfig;
+    private final GenerateOptions generateOptions;
     private final PlanNotebook planNotebook;
     private final ToolExecutionContext toolExecutionContext;
     private final StatePersistence statePersistence;
@@ -159,6 +160,7 @@ private ReActAgent(Builder builder, Toolkit agentToolkit) {
         this.maxIters = builder.maxIters;
         this.modelExecutionConfig = builder.modelExecutionConfig;
         this.toolExecutionConfig = builder.toolExecutionConfig;
+        this.generateOptions = builder.generateOptions;
         this.planNotebook = builder.planNotebook;
         this.toolExecutionContext = builder.toolExecutionContext;
         this.statePersistence =
@@ -575,8 +577,9 @@ private Mono<Msg> acting(int iter) {
             return executeIteration(iter + 1);
         }
 
-        // Set chunk callback for streaming tool responses
-        toolkit.setChunkCallback((toolUse, chunk) -> notifyActingChunk(toolUse, chunk).subscribe());
+        // Forward tool chunks into ActingChunkEvent hooks without overwriting user callbacks.
+        toolkit.setInternalChunkCallback(
+                (toolUse, chunk) -> notifyActingChunk(toolUse, chunk).subscribe());
 
         // Execute only pending tools (those without results in memory)
         return notifyPreActingHooks(pendingToolCalls)
@@ -887,11 +890,17 @@ private List<ToolUseBlock> extractPendingToolCalls() {
 
     @Override
     protected GenerateOptions buildGenerateOptions() {
-        GenerateOptions.Builder builder = GenerateOptions.builder();
+        // Start with user-configured generateOptions if available
+        GenerateOptions baseOptions = generateOptions;
+
+        // If modelExecutionConfig is set, merge it into the options
         if (modelExecutionConfig != null) {
-            builder.executionConfig(modelExecutionConfig);
+            GenerateOptions execConfigOptions =
+                    GenerateOptions.builder().executionConfig(modelExecutionConfig).build();
+            baseOptions = GenerateOptions.mergeOptions(execConfigOptions, baseOptions);
         }
-        return builder.build();
+
+        return baseOptions != null ? baseOptions : GenerateOptions.builder().build();
     }
 
     // ==================== Hook Notification Methods ====================
@@ -1063,6 +1072,15 @@ public PlanNotebook getPlanNotebook() {
         return planNotebook;
     }
 
+    /**
+     * Gets the configured generation options for this agent.
+     *
+     * @return The generation options, or null if not configured
+     */
+    public GenerateOptions getGenerateOptions() {
+        return generateOptions;
+    }
+
     public static Builder builder() {
         return new Builder();
     }
@@ -1080,6 +1098,7 @@ public static class Builder {
         private int maxIters = 10;
         private ExecutionConfig modelExecutionConfig;
         private ExecutionConfig toolExecutionConfig;
+        private GenerateOptions generateOptions;
         private final Set<Hook> hooks = new LinkedHashSet<>();
         private boolean enableMetaTool = false;
         private StructuredOutputReminder structuredOutputReminder =
@@ -1257,6 +1276,39 @@ public Builder toolExecutionConfig(ExecutionConfig toolExecutionConfig) {
             return this;
         }
 
+        /**
+         * Sets the generation options for model API calls.
+         *
+         * <p>This configuration controls LLM generation parameters such as temperature, topP,
+         * maxTokens, frequencyPenalty, presencePenalty, etc. These options are passed to the
+         * model during the reasoning phase.
+         *
+         * <p><b>Example usage:</b>
+         * <pre>{@code
+         * ReActAgent agent = ReActAgent.builder()
+         *     .name("assistant")
+         *     .model(model)
+         *     .generateOptions(GenerateOptions.builder()
+         *         .temperature(0.7)
+         *         .topP(0.9)
+         *         .maxTokens(1000)
+         *         .build())
+         *     .build();
+         * }</pre>
+         *
+         * <p><b>Note:</b> If both generateOptions and modelExecutionConfig are set,
+         * the modelExecutionConfig's executionConfig will be merged into the generateOptions,
+         * with modelExecutionConfig taking precedence for execution settings.
+         *
+         * @param generateOptions The generation options for model calls, can be null
+         * @return This builder instance for method chaining
+         * @see GenerateOptions
+         */
+        public Builder generateOptions(GenerateOptions generateOptions) {
+            this.generateOptions = generateOptions;
+            return this;
+        }
+
         /**
          * Sets the structured output enforcement mode.
          *
@@ -1539,7 +1591,7 @@ private void configureRAG(Toolkit agentToolkit) {
                 case AGENTIC -> {
                     // Register knowledge retrieval tools
                     KnowledgeRetrievalTools tools =
-                            new KnowledgeRetrievalTools(aggregatedKnowledge);
+                            new KnowledgeRetrievalTools(aggregatedKnowledge, retrieveConfig);
                     agentToolkit.registerTool(tools);
                 }
                 case NONE -> {

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

@@ -675,6 +675,19 @@ public final Flux<Event> stream(
         return createEventStream(options, () -> call(msgs, structuredModel));
     }
 
+    /**
+     * Stream with multiple input messages using a JSON schema.
+     *
+     * @param msgs Input messages
+     * @param options Stream configuration options
+     * @param schema JSON schema defining the structure of the response
+     * @return Flux of events emitted during execution
+     */
+    @Override
+    public final Flux<Event> stream(List<Msg> msgs, StreamOptions options, JsonNode schema) {
+        return createEventStream(options, () -> call(msgs, schema));
+    }
+
     /**
      * Helper method to create an event stream with proper hook lifecycle management.
      *

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

@@ -15,6 +15,7 @@
  */
 package io.agentscope.core.agent;
 
+import com.fasterxml.jackson.databind.JsonNode;
 import io.agentscope.core.message.Msg;
 import java.util.List;
 import reactor.core.publisher.Flux;
@@ -98,6 +99,18 @@ default Flux<Event> stream(Msg msg, StreamOptions options, Class<?> structuredMo
         return stream(List.of(msg), options, structuredModel);
     }
 
+    /**
+     * Stream execution events for a single message with JSON schema support.
+     *
+     * @param msg Input message
+     * @param options Stream configuration options
+     * @param schema JSON schema defining the structure
+     * @return Flux of events emitted during execution
+     */
+    default Flux<Event> stream(Msg msg, StreamOptions options, JsonNode schema) {
+        return stream(List.of(msg), options, schema);
+    }
+
     /**
      * Stream execution events for multiple messages with default options.
      *
@@ -126,4 +139,14 @@ default Flux<Event> stream(List<Msg> msgs) {
      * @return Flux of events emitted during execution
      */
     Flux<Event> stream(List<Msg> msgs, StreamOptions options, Class<?> structuredModel);
+
+    /**
+     * Stream execution events with JSON schema support.
+     *
+     * @param msgs Input messages
+     * @param options Stream configuration options
+     * @param schema JSON schema defining the structure
+     * @return Flux of events emitted during execution
+     */
+    Flux<Event> stream(List<Msg> msgs, StreamOptions options, JsonNode schema);
 }

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

@@ -189,9 +189,9 @@ private Mono<Msg> executeWithStructuredOutput(
                                     })
                             .doFinally(
                                     signal -> {
-                                        // Cleanup: remove hook and unregister tool
                                         removeHook(hook);
-                                        toolkit.removeTool(STRUCTURED_OUTPUT_TOOL_NAME);
+                                        toolkit.removeToolIfSame(
+                                                STRUCTURED_OUTPUT_TOOL_NAME, structuredOutputTool);
                                     });
                 });
     }

agentscope-core/src/main/java/io/agentscope/core/formatter/anthropic/AnthropicResponseParser.java

@@ -50,7 +50,7 @@ public static ChatResponse parseMessage(Message message, Instant startTime) {
         List<ContentBlock> contentBlocks = new ArrayList<>();
 
         // Process content blocks
-        for (com.anthropic.models.messages.ContentBlock block : message.content()) {
+        for (var block : message.content()) {
             // Text block
             block.text()
                     .ifPresent(

agentscope-core/src/main/java/io/agentscope/core/formatter/anthropic/AnthropicToolsHelper.java

@@ -15,6 +15,10 @@
  */
 package io.agentscope.core.formatter.anthropic;
 
+import static com.anthropic.models.messages.ToolChoice.ofAny;
+import static com.anthropic.models.messages.ToolChoice.ofAuto;
+import static com.anthropic.models.messages.ToolChoice.ofTool;
+
 import com.anthropic.core.JsonValue;
 import com.anthropic.core.ObjectMappers;
 import com.anthropic.models.messages.MessageCreateParams;
@@ -27,6 +31,7 @@
 import io.agentscope.core.model.ToolSchema;
 import java.util.List;
 import java.util.Map;
+import java.util.function.Function;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -86,27 +91,19 @@ private static JsonValue convertToJsonValue(Object parameters) {
     private static void applyToolChoice(
             MessageCreateParams.Builder builder, ToolChoice toolChoice) {
         if (toolChoice instanceof ToolChoice.Auto) {
-            builder.toolChoice(
-                    com.anthropic.models.messages.ToolChoice.ofAuto(
-                            ToolChoiceAuto.builder().build()));
+            builder.toolChoice(ofAuto(ToolChoiceAuto.builder().build()));
         } else if (toolChoice instanceof ToolChoice.None) {
             // Anthropic doesn't have None, use Any instead
-            builder.toolChoice(
-                    com.anthropic.models.messages.ToolChoice.ofAny(
-                            ToolChoiceAny.builder().build()));
+            builder.toolChoice(ofAny(ToolChoiceAny.builder().build()));
         } else if (toolChoice instanceof ToolChoice.Required) {
             // Anthropic doesn't have a direct "required" option, use "any" which forces tool
             // use
             log.warn(
                     "Anthropic API doesn't support ToolChoice.Required directly, using 'any'"
                             + " instead");
-            builder.toolChoice(
-                    com.anthropic.models.messages.ToolChoice.ofAny(
-                            ToolChoiceAny.builder().build()));
+            builder.toolChoice(ofAny(ToolChoiceAny.builder().build()));
         } else if (toolChoice instanceof ToolChoice.Specific specific) {
-            builder.toolChoice(
-                    com.anthropic.models.messages.ToolChoice.ofTool(
-                            ToolChoiceTool.builder().name(specific.toolName()).build()));
+            builder.toolChoice(ofTool(ToolChoiceTool.builder().name(specific.toolName()).build()));
         } else {
             log.warn("Unknown tool choice type: {}", toolChoice);
         }
@@ -203,7 +200,7 @@ private static void applyAdditionalQueryParams(
     private static <T> T getOption(
             GenerateOptions options,
             GenerateOptions defaultOptions,
-            java.util.function.Function<GenerateOptions, T> getter) {
+            Function<GenerateOptions, T> getter) {
         if (options != null) {
             T value = getter.apply(options);
             if (value != null) {

agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeChatFormatter.java

@@ -29,6 +29,7 @@
 import java.time.Instant;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import java.util.stream.Collectors;
 
 /**
@@ -41,6 +42,8 @@
 public class DashScopeChatFormatter
         extends AbstractBaseFormatter<DashScopeMessage, DashScopeResponse, DashScopeRequest> {
 
+    private static final Map<String, String> EPHEMERAL_CACHE_CONTROL = Map.of("type", "ephemeral");
+
     private final DashScopeMessageConverter messageConverter;
     private final DashScopeResponseParser responseParser;
     private final DashScopeToolsHelper toolsHelper;
@@ -168,4 +171,37 @@ public DashScopeRequest buildRequest(
 
         return request;
     }
+
+    /**
+     * Apply cache control to DashScope messages.
+     *
+     * <p>Adds <code>cache_control: {"type": "ephemeral"}</code> to all system messages and the last
+     * message in the list. Messages that already have cache_control set (e.g., via manual metadata
+     * marking) will not be overwritten.
+     *
+     * @param messages the list of formatted DashScope messages
+     */
+    public void applyCacheControl(List<DashScopeMessage> messages) {
+        if (messages == null || messages.isEmpty()) {
+            return;
+        }
+        for (DashScopeMessage msg : messages) {
+            if ("system".equals(msg.getRole()) && msg.getCacheControl() == null) {
+                msg.setCacheControl(EPHEMERAL_CACHE_CONTROL);
+            }
+        }
+        DashScopeMessage lastMsg = messages.get(messages.size() - 1);
+        if (lastMsg.getCacheControl() == null) {
+            lastMsg.setCacheControl(EPHEMERAL_CACHE_CONTROL);
+        }
+    }
+
+    /**
+     * Get the ephemeral cache control constant.
+     *
+     * @return unmodifiable map representing ephemeral cache control
+     */
+    static Map<String, String> getEphemeralCacheControl() {
+        return EPHEMERAL_CACHE_CONTROL;
+    }
 }

agentscope-core/src/main/java/io/agentscope/core/formatter/dashscope/DashScopeMessageConverter.java

@@ -20,6 +20,7 @@
 import io.agentscope.core.message.AudioBlock;
 import io.agentscope.core.message.ContentBlock;
 import io.agentscope.core.message.ImageBlock;
+import io.agentscope.core.message.MessageMetadataKeys;
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.message.MsgRole;
 import io.agentscope.core.message.TextBlock;
@@ -64,11 +65,17 @@ public DashScopeMessageConverter(Function<List<ContentBlock>, String> toolResult
      * @return The converted DashScopeMessage
      */
     public DashScopeMessage convertToMessage(Msg msg, boolean useMultimodalFormat) {
+        DashScopeMessage result;
         if (useMultimodalFormat) {
-            return convertToMultimodalContent(msg);
+            result = convertToMultimodalContent(msg);
         } else {
-            return convertToSimpleContent(msg);
+            result = convertToSimpleContent(msg);
         }
+
+        // Apply cache_control from message metadata if manually marked
+        applyCacheControlFromMetadata(msg, result);
+
+        return result;
     }
 
     /**
@@ -237,4 +244,20 @@ private String extractTextContent(Msg msg) {
                 .map(block -> ((TextBlock) block).getText())
                 .reduce("", (a, b) -> a.isEmpty() ? b : a + "\n" + b);
     }
+
+    /**
+     * Apply cache_control from Msg metadata to the converted DashScopeMessage.
+     *
+     * @param msg the source message with metadata
+     * @param result the converted DashScope message
+     */
+    private void applyCacheControlFromMetadata(Msg msg, DashScopeMessage result) {
+        if (msg.getMetadata() == null) {
+            return;
+        }
+        Object cacheFlag = msg.getMetadata().get(MessageMetadataKeys.CACHE_CONTROL);
+        if (Boolean.TRUE.equals(cacheFlag)) {
+            result.setCacheControl(DashScopeChatFormatter.getEphemeralCacheControl());
+        }
+    }
 }