fix(core): wire fallback model into ReActAgent

Author: guslegend

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

@@ -83,6 +83,7 @@
 import io.agentscope.core.middleware.MiddlewareChain;
 import io.agentscope.core.middleware.ModelCallInput;
 import io.agentscope.core.middleware.ReasoningInput;
+import io.agentscope.core.model.ChatResponse;
 import io.agentscope.core.model.ChatUsage;
 import io.agentscope.core.model.ExecutionConfig;
 import io.agentscope.core.model.GenerateOptions;
@@ -2083,7 +2084,7 @@ Flux<AgentEvent> reasoningStream(
                             rc,
                             MiddlewareBase::onModelCall,
                             modelCallCore)
-                    .apply(new ModelCallInput(messages, tools, options, model))
+                    .apply(new ModelCallInput(messages, tools, options, modelForCall()))
                     .doOnNext(this::publishEvent);
         }
 
@@ -2994,7 +2995,7 @@ Flux<AgentEvent> summaryStream(
                             rc,
                             MiddlewareBase::onModelCall,
                             summaryModelCallCore)
-                    .apply(new ModelCallInput(messages, null, options, model))
+                    .apply(new ModelCallInput(messages, null, options, modelForCall()))
                     .doOnNext(this::publishEvent);
         }
 
@@ -3246,6 +3247,18 @@ protected GenerateOptions buildGenerateOptions() {
         // Start with user-configured generateOptions if available
         GenerateOptions baseOptions = generateOptions;
 
+        // Layer the agent-level retry budget underneath explicit per-call settings.
+        if (modelConfig != null) {
+            GenerateOptions retryBudgetOptions =
+                    GenerateOptions.builder()
+                            .executionConfig(
+                                    ExecutionConfig.builder()
+                                            .maxAttempts(modelConfig.maxRetries())
+                                            .build())
+                            .build();
+            baseOptions = GenerateOptions.mergeOptions(baseOptions, retryBudgetOptions);
+        }
+
         // If modelExecutionConfig is set, merge it into the options
         if (modelExecutionConfig != null) {
             GenerateOptions execConfigOptions =
@@ -3256,6 +3269,41 @@ protected GenerateOptions buildGenerateOptions() {
         return baseOptions != null ? baseOptions : GenerateOptions.builder().build();
     }
 
+    private Model modelForCall() {
+        Model fallbackModel = modelConfig.fallbackModel();
+        if (fallbackModel == null) {
+            return model;
+        }
+
+        AtomicReference<Model> activeModel = new AtomicReference<>(model);
+        return new Model() {
+            @Override
+            public Flux<ChatResponse> stream(
+                    List<Msg> messages, List<ToolSchema> tools, GenerateOptions options) {
+                Flux<ChatResponse> primaryFlux = model.stream(messages, tools, options);
+                return primaryFlux.switchOnFirst(
+                        (signal, flux) -> {
+                            if (signal.isOnError()) {
+                                Throwable error = signal.getThrowable();
+                                activeModel.set(fallbackModel);
+                                log.warn(
+                                        "Primary model {} failed, switching to fallback {}",
+                                        model.getModelName(),
+                                        fallbackModel.getModelName(),
+                                        error);
+                                return fallbackModel.stream(messages, tools, options);
+                            }
+                            return flux;
+                        });
+            }
+
+            @Override
+            public String getModelName() {
+                return activeModel.get().getModelName();
+            }
+        };
+    }
+
     @Override
     protected Mono<Msg> handleInterrupt(InterruptContext context, Msg... originalArgs) {
         return Mono.deferContextual(
@@ -4167,6 +4215,11 @@ public static Builder fromAgent(ReActAgent agent) {
             b.model = agent.getModel();
             b.maxIters = agent.getMaxIters();
             b.generateOptions = agent.getGenerateOptions();
+            ModelConfig srcModelConfig = agent.getModelConfig();
+            if (srcModelConfig != null) {
+                b.flatMaxRetries = srcModelConfig.maxRetries();
+                b.flatFallbackModel = srcModelConfig.fallbackModel();
+            }
             b.toolkit = agent.getToolkit().copy();
             return b;
         }

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

@@ -110,6 +110,29 @@ void builderAppliesDefaultsWhenConfigsOmitted() {
         assertTrue(agent.getMiddlewares().get(0) instanceof GracefulShutdownMiddleware);
     }
 
+    @Test
+    void fromAgentCopiesModelResilienceConfig() {
+        ChatModelBase model = newFakeModel();
+        ChatModelBase fallback = newFakeModel();
+
+        ReActAgent source =
+                ReActAgent.builder()
+                        .name("source")
+                        .sysPrompt("sys")
+                        .model(model)
+                        .fallbackModel(fallback)
+                        .maxRetries(7)
+                        .toolkit(new Toolkit())
+                        .build();
+
+        ReActAgent copy = ReActAgent.Builder.fromAgent(source).build();
+
+        assertNotNull(copy.getModelConfig());
+        assertEquals(7, copy.getModelConfig().maxRetries());
+        assertSame(fallback, copy.getModelConfig().fallbackModel());
+        assertSame(model, copy.getModel());
+    }
+
     @Test
     void observeAddsMessagesToState() {
         ReActAgent agent =

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

@@ -552,6 +552,32 @@ void testErrorHandling() {
         }
     }
 
+    @Test
+    @DisplayName("Should switch to fallback model when primary fails")
+    void testFallbackModel() {
+        String errorMessage = "Primary model unavailable";
+        MockModel primaryModel = new MockModel("").withError(errorMessage);
+        MockModel fallbackModel = new MockModel("Fallback response");
+
+        agent =
+                ReActAgent.builder()
+                        .name(TestConstants.TEST_REACT_AGENT_NAME)
+                        .sysPrompt(TestConstants.DEFAULT_SYS_PROMPT)
+                        .model(primaryModel)
+                        .fallbackModel(fallbackModel)
+                        .toolkit(mockToolkit)
+                        .build();
+
+        Msg userMsg = TestUtils.createUserMessage("User", TestConstants.TEST_USER_INPUT);
+        Msg response =
+                agent.call(userMsg).block(Duration.ofMillis(TestConstants.DEFAULT_TEST_TIMEOUT_MS));
+
+        assertNotNull(response, "Response should not be null");
+        assertEquals("Fallback response", TestUtils.extractTextContent(response));
+        assertEquals(1, primaryModel.getCallCount(), "Primary model should be tried once");
+        assertEquals(1, fallbackModel.getCallCount(), "Fallback model should be called once");
+    }
+
     @Test
     @DisplayName("Should support streaming responses")
     void testStreaming() {