feat: add missing tool resolution strategy

Author: tkroman

core/src/main/java/com/google/adk/agents/InvocationContext.java

@@ -86,7 +86,9 @@ public InvocationContext(
           "this(sessionService, artifactService, memoryService, new"
               + " PluginManager(), liveRequestQueue, branch, invocationId, agent,"
               + " session, userContent, runConfig, endInvocation)",
-      imports = "com.google.adk.plugins.PluginManager")
+      imports = {
+        "com.google.adk.plugins.PluginManager",
+      })
   @Deprecated
   public InvocationContext(
       BaseSessionService sessionService,

core/src/main/java/com/google/adk/agents/RunConfig.java

@@ -16,6 +16,7 @@
 
 package com.google.adk.agents;
 
+import com.google.adk.tools.MissingToolResolutionStrategy;
 import com.google.auto.value.AutoValue;
 import com.google.common.collect.ImmutableList;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
@@ -70,6 +71,8 @@ public enum ToolExecutionMode {
 
   public abstract int maxLlmCalls();
 
+  public abstract MissingToolResolutionStrategy missingToolResolutionStrategy();
+
   public abstract Builder toBuilder();
 
   public static Builder builder() {
@@ -78,6 +81,7 @@ public static Builder builder() {
         .setResponseModalities(ImmutableList.of())
         .setStreamingMode(StreamingMode.NONE)
         .setToolExecutionMode(ToolExecutionMode.NONE)
+        .setMissingToolResolutionStrategy(MissingToolResolutionStrategy.THROW_EXCEPTION)
         .setMaxLlmCalls(500);
   }
 
@@ -90,7 +94,8 @@ public static Builder builder(RunConfig runConfig) {
         .setResponseModalities(runConfig.responseModalities())
         .setSpeechConfig(runConfig.speechConfig())
         .setOutputAudioTranscription(runConfig.outputAudioTranscription())
-        .setInputAudioTranscription(runConfig.inputAudioTranscription());
+        .setInputAudioTranscription(runConfig.inputAudioTranscription())
+        .setMissingToolResolutionStrategy(runConfig.missingToolResolutionStrategy());
   }
 
   /** Builder for {@link RunConfig}. */
@@ -123,6 +128,10 @@ public abstract Builder setInputAudioTranscription(
     @CanIgnoreReturnValue
     public abstract Builder setMaxLlmCalls(int maxLlmCalls);
 
+    @CanIgnoreReturnValue
+    public abstract Builder setMissingToolResolutionStrategy(
+        MissingToolResolutionStrategy missingToolResolutionStrategy);
+
     abstract RunConfig autoBuild();
 
     public RunConfig build() {

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

@@ -30,9 +30,9 @@
 import com.google.adk.events.EventActions;
 import com.google.adk.tools.BaseTool;
 import com.google.adk.tools.FunctionTool;
+import com.google.adk.tools.MissingToolResolutionStrategy;
 import com.google.adk.tools.ToolConfirmation;
 import com.google.adk.tools.ToolContext;
-import com.google.common.base.VerifyException;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.genai.types.Content;
@@ -127,7 +127,7 @@ public static void populateClientFunctionCallId(Event modelResponseEvent) {
   /** Handles standard, non-streaming function calls. */
   public static Maybe<Event> handleFunctionCalls(
       InvocationContext invocationContext, Event functionCallEvent, Map<String, BaseTool> tools) {
-    return handleFunctionCalls(invocationContext, functionCallEvent, tools, ImmutableMap.of());
+    return handleFunctionCalls(invocationContext, functionCallEvent, tools);
   }
 
   /** Handles standard, non-streaming function calls with tool confirmations. */
@@ -137,10 +137,13 @@ public static Maybe<Event> handleFunctionCalls(
       Map<String, BaseTool> tools,
       Map<String, ToolConfirmation> toolConfirmations) {
     ImmutableList<FunctionCall> functionCalls = functionCallEvent.functionCalls();
-
+    MissingToolResolutionStrategy missingToolResolutionStrategy =
+        invocationContext.runConfig().missingToolResolutionStrategy();
+    ImmutableList.Builder<Maybe<Event>> missingTools = ImmutableList.builder();
     for (FunctionCall functionCall : functionCalls) {
       if (!tools.containsKey(functionCall.name().get())) {
-        throw new VerifyException("Tool not found: " + functionCall.name().get());
+        missingTools.add(
+            missingToolResolutionStrategy.onMissingTool(invocationContext, functionCall));
       }
     }
 
@@ -207,7 +210,11 @@ public static Maybe<Event> handleFunctionCalls(
       functionResponseEventsFlowable =
           Flowable.fromIterable(functionCalls).flatMapMaybe(functionCallMapper);
     }
-    return functionResponseEventsFlowable
+    Flowable<Event> missingToolsFlowable =
+        Flowable.fromIterable(missingTools.build()).concatMapMaybe(maybe -> maybe);
+    Flowable<Event> allEventsFlowable =
+        Flowable.concat(missingToolsFlowable, functionResponseEventsFlowable);
+    return allEventsFlowable
         .toList()
         .flatMapMaybe(
             events -> {
@@ -242,10 +249,14 @@ public static Maybe<Event> handleFunctionCalls(
   public static Maybe<Event> handleFunctionCallsLive(
       InvocationContext invocationContext, Event functionCallEvent, Map<String, BaseTool> tools) {
     ImmutableList<FunctionCall> functionCalls = functionCallEvent.functionCalls();
+    MissingToolResolutionStrategy missingToolResolutionStrategy =
+        invocationContext.runConfig().missingToolResolutionStrategy();
 
+    ImmutableList.Builder<Maybe<Event>> missingTools = ImmutableList.builder();
     for (FunctionCall functionCall : functionCalls) {
       if (!tools.containsKey(functionCall.name().get())) {
-        throw new VerifyException("Tool not found: " + functionCall.name().get());
+        missingTools.add(
+            missingToolResolutionStrategy.onMissingTool(invocationContext, functionCall));
       }
     }
 
@@ -311,7 +322,6 @@ public static Maybe<Event> handleFunctionCallsLive(
         };
 
     Flowable<Event> responseEventsFlowable;
-
     if (invocationContext.runConfig().toolExecutionMode() == ToolExecutionMode.SEQUENTIAL) {
       responseEventsFlowable =
           Flowable.fromIterable(functionCalls).concatMapMaybe(functionCallMapper);
@@ -320,8 +330,12 @@ public static Maybe<Event> handleFunctionCallsLive(
       responseEventsFlowable =
           Flowable.fromIterable(functionCalls).flatMapMaybe(functionCallMapper);
     }
+    Flowable<Event> missingToolsFlowable =
+        Flowable.fromIterable(missingTools.build()).concatMapMaybe(maybe -> maybe);
+    Flowable<Event> allEventsFlowable =
+        Flowable.concat(missingToolsFlowable, responseEventsFlowable);
 
-    return responseEventsFlowable
+    return allEventsFlowable
         .toList()
         .flatMapMaybe(
             events -> {

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

@@ -0,0 +1,60 @@
+package com.google.adk.tools;
+
+import com.google.adk.agents.InvocationContext;
+import com.google.adk.events.Event;
+import com.google.common.base.VerifyException;
+import com.google.genai.types.FunctionCall;
+import io.reactivex.rxjava3.core.Maybe;
+import java.util.function.BiFunction;
+
+public interface MissingToolResolutionStrategy {
+  public static final MissingToolResolutionStrategy THROW_EXCEPTION =
+      new MissingToolResolutionStrategy() {
+        @Override
+        public Maybe<Event> onMissingTool(
+            InvocationContext invocationContext, FunctionCall functionCall) {
+          throw new VerifyException(
+              "Tool not found: " + functionCall.name().orElse(functionCall.toJson()));
+        }
+      };
+
+  public static final MissingToolResolutionStrategy RETURN_ERROR =
+      new MissingToolResolutionStrategy() {
+        @Override
+        public Maybe<Event> onMissingTool(
+            InvocationContext invocationContext, FunctionCall functionCall) {
+          return Maybe.error(
+              new VerifyException(
+                  "Tool not found: " + functionCall.name().orElse(functionCall.toJson())));
+        }
+      };
+
+  public static final MissingToolResolutionStrategy IGNORE =
+      new MissingToolResolutionStrategy() {
+        @Override
+        public Maybe<Event> onMissingTool(
+            InvocationContext invocationContext, FunctionCall functionCall) {
+          return Maybe.empty();
+        }
+      };
+
+  public static MissingToolResolutionStrategy respondWithEvent(
+      BiFunction<InvocationContext, FunctionCall, Maybe<Event>> eventFactory) {
+    return new MissingToolResolutionStrategy() {
+      @Override
+      public Maybe<Event> onMissingTool(
+          InvocationContext invocationContext, FunctionCall functionCall) {
+        return eventFactory.apply(invocationContext, functionCall);
+      }
+    };
+  }
+
+  public static MissingToolResolutionStrategy respondWithEventSync(
+      BiFunction<InvocationContext, FunctionCall, Event> eventFactory) {
+    return respondWithEvent(
+        (invocationContext, functionCall) ->
+            Maybe.just(eventFactory.apply(invocationContext, functionCall)));
+  }
+
+  Maybe<Event> onMissingTool(InvocationContext invocationContext, FunctionCall functionCall);
+}

core/src/test/java/com/google/adk/flows/llmflows/FunctionsTest.java

@@ -23,8 +23,10 @@
 import static org.junit.Assert.assertThrows;
 
 import com.google.adk.agents.InvocationContext;
+import com.google.adk.agents.RunConfig;
 import com.google.adk.events.Event;
 import com.google.adk.testing.TestUtils;
+import com.google.adk.tools.MissingToolResolutionStrategy;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.genai.types.Content;
@@ -67,6 +69,37 @@ public void handleFunctionCalls_missingTool() {
                 invocationContext, event, /* tools= */ ImmutableMap.of()));
   }
 
+  @Test
+  public void handleFunctionCalls_missingTool_recoveryStrategy() {
+    InvocationContext invocationContext =
+        createInvocationContext(
+            createRootAgent(),
+            RunConfig.builder()
+                .setMissingToolResolutionStrategy(
+                    MissingToolResolutionStrategy.respondWithEventSync(
+                        (ctx, call) ->
+                            Event.builder()
+                                .content(
+                                    Content.fromParts(
+                                        Part.fromText("tool missing: " + call.name().get())))
+                                .build()))
+                .build());
+    Event event =
+        createEvent("event").toBuilder()
+            .content(
+                Content.fromParts(
+                    Part.fromText("..."), Part.fromFunctionCall("missing_tool", ImmutableMap.of())))
+            .build();
+
+    Event functionResponseEvent =
+        Functions.handleFunctionCalls(invocationContext, event, /* tools= */ ImmutableMap.of())
+            .blockingGet();
+
+    assertThat(functionResponseEvent).isNotNull();
+    assertThat(functionResponseEvent.content().get().parts().get())
+        .containsExactly(Part.fromText("tool missing: missing_tool"));
+  }
+
   @Test
   public void handleFunctionCalls_singleFunctionCall() {
     InvocationContext invocationContext = createInvocationContext(createRootAgent());