feat: enabling output_schema and tools to coexist

This CL enables the simultaneous use of `output_schema` (structured output) and `tools` for models that do not natively support both features at once (specifically Gemini 1.x and 2.x on Vertex AI).

### Core Logic
The CL implements a workaround for models with this limitation:
1.  **Synthetic Tooling**: Instead of passing the `output_schema` directly to the model's configuration, it introduces a synthetic tool called `set_model_response`.
2.  **Schema Injection**: The parameters of this tool are set to the requested `output_schema`.
3.  **Instruction Prompting**: System instructions are appended, directing the model to provide its final response using this specific tool in the required format.
4.  **Response Interception**: The `BaseLlmFlow` is updated to check if `set_model_response` was called. If so, it extracts the JSON arguments and converts them into a standard model response event.

### Key Changes
*   **`OutputSchema.java` (New)**: A new `RequestProcessor` that detects when the workaround is needed, adds the `SetModelResponseTool`, and provides utilities for extracting the structured response.
*   **`SetModelResponseTool.java` (New)**: A marker tool that simply returns its input arguments, used to "capture" the structured output from the model.
*   **`ModelNameUtils.java`**: Added logic to identify Gemini 1.x and 2.x models and determine if they can handle native `output_schema` alongside tools.
*   **`BaseLlmFlow.java`**: Updated the flow logic to detect the synthetic tool response and generate the final output event.
*   **`Basic.java`**: Updated to prevent native `outputSchema` configuration when the workaround is active.
*   **`SingleFlow.java`**: Registered the new `OutputSchema` processor.

PiperOrigin-RevId: 886769688

Author: google-genai-bot

core/src/main/java/com/google/adk/flows/llmflows/BaseLlmFlow.java

@@ -692,9 +692,14 @@ private Flowable<Event> buildPostprocessingEvents(
                 Optional<Event> toolConfirmationEvent =
                     Functions.generateRequestConfirmationEvent(
                         context, modelResponseEvent, functionResponseEvent);
-                return toolConfirmationEvent.isPresent()
-                    ? Flowable.just(toolConfirmationEvent.get(), functionResponseEvent)
-                    : Flowable.just(functionResponseEvent);
+                List<Event> events = new ArrayList<>();
+                toolConfirmationEvent.ifPresent(events::add);
+                events.add(functionResponseEvent);
+                OutputSchema.getStructuredModelResponse(functionResponseEvent)
+                    .ifPresent(
+                        json ->
+                            events.add(OutputSchema.createFinalModelResponseEvent(context, json)));
+                return Flowable.fromIterable(events);
               });
     }
 

core/src/main/java/com/google/adk/flows/llmflows/Basic.java

@@ -19,6 +19,7 @@
 import com.google.adk.agents.InvocationContext;
 import com.google.adk.agents.LlmAgent;
 import com.google.adk.models.LlmRequest;
+import com.google.adk.utils.ModelNameUtils;
 import com.google.common.collect.ImmutableList;
 import com.google.genai.types.GenerateContentConfig;
 import com.google.genai.types.LiveConnectConfig;
@@ -60,7 +61,15 @@ public Single<RequestProcessor.RequestProcessingResult> processRequest(
                     .orElseGet(() -> GenerateContentConfig.builder().build()))
             .liveConnectConfig(liveConnectConfigBuilder.build());
 
-    agent.outputSchema().ifPresent(builder::outputSchema);
+    agent
+        .outputSchema()
+        .ifPresent(
+            outputSchema -> {
+              if (agent.toolsUnion().isEmpty()
+                  || ModelNameUtils.canUseOutputSchemaWithTools(modelName)) {
+                builder.outputSchema(outputSchema);
+              }
+            });
     return Single.just(
         RequestProcessor.RequestProcessingResult.create(builder.build(), ImmutableList.of()));
   }

core/src/main/java/com/google/adk/flows/llmflows/OutputSchema.java

@@ -0,0 +1,119 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * 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 com.google.adk.flows.llmflows;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.google.adk.JsonBaseModel;
+import com.google.adk.agents.InvocationContext;
+import com.google.adk.agents.LlmAgent;
+import com.google.adk.events.Event;
+import com.google.adk.models.LlmRequest;
+import com.google.adk.tools.SetModelResponseTool;
+import com.google.adk.tools.ToolContext;
+import com.google.adk.utils.ModelNameUtils;
+import com.google.common.collect.ImmutableList;
+import com.google.genai.types.Content;
+import com.google.genai.types.FunctionResponse;
+import com.google.genai.types.Part;
+import io.reactivex.rxjava3.core.Single;
+import java.util.Objects;
+import java.util.Optional;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/** Processor that handles output schema for agents with tools. */
+public final class OutputSchema implements RequestProcessor {
+
+  private static final Logger logger = LoggerFactory.getLogger(OutputSchema.class);
+
+  public OutputSchema() {}
+
+  @Override
+  public Single<RequestProcessingResult> processRequest(
+      InvocationContext context, LlmRequest request) {
+    if (!(context.agent() instanceof LlmAgent)) {
+      return Single.just(RequestProcessingResult.create(request, ImmutableList.of()));
+    }
+    LlmAgent agent = (LlmAgent) context.agent();
+    String modelName = request.model().orElse("");
+
+    if (agent.outputSchema().isEmpty()
+        || agent.toolsUnion().isEmpty()
+        || ModelNameUtils.canUseOutputSchemaWithTools(modelName)) {
+      return Single.just(RequestProcessingResult.create(request, ImmutableList.of()));
+    }
+
+    // Add the set_model_response tool to handle structured output
+    SetModelResponseTool setResponseTool = new SetModelResponseTool(agent.outputSchema().get());
+    LlmRequest.Builder builder = request.toBuilder();
+
+    return setResponseTool
+        .processLlmRequest(builder, ToolContext.builder(context).build())
+        .andThen(
+            Single.fromCallable(
+                () -> {
+                  builder.appendInstructions(
+                      ImmutableList.of(
+                          "IMPORTANT: You have access to other tools, but you must provide your"
+                              + " final response using the set_model_response tool with the"
+                              + " required structured format. After using any other tools needed"
+                              + " to complete the task, always call set_model_response with your"
+                              + " final answer in the specified schema format."));
+                  return RequestProcessingResult.create(builder.build(), ImmutableList.of());
+                }));
+  }
+
+  /**
+   * Check if function response contains set_model_response and extract JSON.
+   *
+   * @param functionResponseEvent The function response event to check.
+   * @return JSON response string if set_model_response was called, Optional.empty() otherwise.
+   */
+  public static Optional<String> getStructuredModelResponse(Event functionResponseEvent) {
+    for (FunctionResponse funcResponse : functionResponseEvent.functionResponses()) {
+      if (Objects.equals(funcResponse.name().orElse(""), SetModelResponseTool.NAME)) {
+        Object response = funcResponse.response();
+        // The tool returns the args map directly.
+        try {
+          return Optional.of(JsonBaseModel.getMapper().writeValueAsString(response));
+        } catch (JsonProcessingException e) {
+          logger.error("Failed to serialize set_model_response result", e);
+          return Optional.empty();
+        }
+      }
+    }
+    return Optional.empty();
+  }
+
+  /**
+   * Create a final model response event from set_model_response JSON.
+   *
+   * @param context The invocation context.
+   * @param jsonResponse The JSON response from set_model_response tool.
+   * @return A new Event that looks like a normal model response.
+   */
+  public static Event createFinalModelResponseEvent(
+      InvocationContext context, String jsonResponse) {
+    return Event.builder()
+        .id(Event.generateEventId())
+        .invocationId(context.invocationId())
+        .author(context.agent().name())
+        .branch(context.branch().orElse(null))
+        .content(Content.builder().role("model").parts(Part.fromText(jsonResponse)).build())
+        .build();
+  }
+}

core/src/main/java/com/google/adk/flows/llmflows/SingleFlow.java

@@ -27,6 +27,7 @@ public class SingleFlow extends BaseLlmFlow {
   protected static final ImmutableList<RequestProcessor> REQUEST_PROCESSORS =
       ImmutableList.of(
           new Basic(),
+          new OutputSchema(),
           new RequestConfirmationLlmRequestProcessor(),
           new Instructions(),
           new Identity(),

core/src/main/java/com/google/adk/tools/SetModelResponseTool.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * 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 com.google.adk.tools;
+
+import com.google.genai.types.FunctionDeclaration;
+import com.google.genai.types.Schema;
+import io.reactivex.rxjava3.core.Single;
+import java.util.Map;
+import java.util.Optional;
+import javax.annotation.Nonnull;
+
+/**
+ * Internal tool used for output schema workaround.
+ *
+ * <p>This tool allows the model to set its final response when output_schema is configured
+ * alongside other tools. The model should use this tool to provide its final structured response
+ * instead of outputting text directly.
+ */
+public class SetModelResponseTool extends BaseTool {
+  public static final String NAME = "set_model_response";
+
+  private final Schema outputSchema;
+
+  public SetModelResponseTool(@Nonnull Schema outputSchema) {
+    super(
+        NAME,
+        "Set your final response using the required output schema. "
+            + "After using any other tools needed to complete the task, always call"
+            + " set_model_response with your final answer in the specified schema format.");
+    this.outputSchema = outputSchema;
+  }
+
+  @Override
+  public Optional<FunctionDeclaration> declaration() {
+    return Optional.of(
+        FunctionDeclaration.builder()
+            .name(name())
+            .description(description())
+            .parameters(outputSchema)
+            .build());
+  }
+
+  @Override
+  public Single<Map<String, Object>> runAsync(Map<String, Object> args, ToolContext toolContext) {
+    // This tool is a marker for the final response, it doesn't do anything but return its arguments
+    // which will be captured as the final result.
+    return Single.just(args);
+  }
+}

core/src/main/java/com/google/adk/utils/ModelNameUtils.java

@@ -21,6 +21,7 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/** Utility class for model names. */
 public final class ModelNameUtils {
   private static final String GEMINI_PREFIX = "gemini-";
   private static final Pattern GEMINI_2_PATTERN = Pattern.compile("^gemini-2\\..*");
@@ -35,11 +36,15 @@ public static boolean isGeminiModel(String modelString) {
   }
 
   public static boolean isGemini2Model(String modelString) {
+    return matchesModelPattern(modelString, GEMINI_2_PATTERN);
+  }
+
+  private static boolean matchesModelPattern(String modelString, Pattern pattern) {
     if (modelString == null) {
       return false;
     }
     String modelName = extractModelName(modelString);
-    return GEMINI_2_PATTERN.matcher(modelName).matches();
+    return pattern.matcher(modelName).matches();
   }
 
   /**
@@ -65,6 +70,17 @@ public static boolean isInstanceOfGemini(Object o) {
     return false;
   }
 
+  /**
+   * Returns true if the model supports using output schema together with tools.
+   *
+   * @param modelString The model name or path.
+   * @return true if output schema with tools is supported, false otherwise.
+   */
+  public static boolean canUseOutputSchemaWithTools(String modelString) {
+    // Current limitation for Vertex AI 2.x models.
+    return !isGemini2Model(modelString);
+  }
+
   /**
    * Extract the actual model name from either simple or path-based format.
    *