feat: Add HITL tool confirmation support to ADK/Java

This is a port of the python implementation and part of the "human in the loop" workflow.

PiperOrigin-RevId: 820215719

Author: google-genai-bot

core/src/main/java/com/google/adk/events/EventActions.java

@@ -17,6 +17,7 @@
 
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.google.adk.tools.ToolConfirmation;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import com.google.genai.types.Part;
 import java.util.Objects;
@@ -37,6 +38,8 @@ public class EventActions {
   private Optional<Boolean> escalate = Optional.empty();
   private ConcurrentMap<String, ConcurrentMap<String, Object>> requestedAuthConfigs =
       new ConcurrentHashMap<>();
+  private ConcurrentMap<String, ToolConfirmation> requestedToolConfirmations =
+      new ConcurrentHashMap<>();
   private Optional<Boolean> endInvocation = Optional.empty();
 
   /** Default constructor for Jackson. */
@@ -113,6 +116,16 @@ public void setRequestedAuthConfigs(
     this.requestedAuthConfigs = requestedAuthConfigs;
   }
 
+  @JsonProperty("requestedToolConfirmations")
+  public ConcurrentMap<String, ToolConfirmation> requestedToolConfirmations() {
+    return requestedToolConfirmations;
+  }
+
+  public void setRequestedToolConfirmations(
+      ConcurrentMap<String, ToolConfirmation> requestedToolConfirmations) {
+    this.requestedToolConfirmations = requestedToolConfirmations;
+  }
+
   @JsonProperty("endInvocation")
   public Optional<Boolean> endInvocation() {
     return endInvocation;
@@ -148,6 +161,7 @@ public boolean equals(Object o) {
         && Objects.equals(transferToAgent, that.transferToAgent)
         && Objects.equals(escalate, that.escalate)
         && Objects.equals(requestedAuthConfigs, that.requestedAuthConfigs)
+        && Objects.equals(requestedToolConfirmations, that.requestedToolConfirmations)
         && Objects.equals(endInvocation, that.endInvocation);
   }
 
@@ -160,6 +174,7 @@ public int hashCode() {
         transferToAgent,
         escalate,
         requestedAuthConfigs,
+        requestedToolConfirmations,
         endInvocation);
   }
 
@@ -172,6 +187,8 @@ public static class Builder {
     private Optional<Boolean> escalate = Optional.empty();
     private ConcurrentMap<String, ConcurrentMap<String, Object>> requestedAuthConfigs =
         new ConcurrentHashMap<>();
+    private ConcurrentMap<String, ToolConfirmation> requestedToolConfirmations =
+        new ConcurrentHashMap<>();
     private Optional<Boolean> endInvocation = Optional.empty();
 
     public Builder() {}
@@ -183,6 +200,8 @@ private Builder(EventActions eventActions) {
       this.transferToAgent = eventActions.transferToAgent();
       this.escalate = eventActions.escalate();
       this.requestedAuthConfigs = new ConcurrentHashMap<>(eventActions.requestedAuthConfigs());
+      this.requestedToolConfirmations =
+          new ConcurrentHashMap<>(eventActions.requestedToolConfirmations());
       this.endInvocation = eventActions.endInvocation();
     }
 
@@ -229,6 +248,13 @@ public Builder requestedAuthConfigs(
       return this;
     }
 
+    @CanIgnoreReturnValue
+    @JsonProperty("requestedToolConfirmations")
+    public Builder requestedToolConfirmations(ConcurrentMap<String, ToolConfirmation> value) {
+      this.requestedToolConfirmations = value;
+      return this;
+    }
+
     @CanIgnoreReturnValue
     @JsonProperty("endInvocation")
     public Builder endInvocation(boolean endInvocation) {
@@ -256,6 +282,9 @@ public Builder merge(EventActions other) {
       if (other.requestedAuthConfigs() != null) {
         this.requestedAuthConfigs.putAll(other.requestedAuthConfigs());
       }
+      if (other.requestedToolConfirmations() != null) {
+        this.requestedToolConfirmations.putAll(other.requestedToolConfirmations());
+      }
       if (other.endInvocation().isPresent()) {
         this.endInvocation = other.endInvocation();
       }
@@ -270,6 +299,7 @@ public EventActions build() {
       eventActions.setTransferToAgent(this.transferToAgent);
       eventActions.setEscalate(this.escalate);
       eventActions.setRequestedAuthConfigs(this.requestedAuthConfigs);
+      eventActions.setRequestedToolConfirmations(this.requestedToolConfirmations);
       eventActions.setEndInvocation(this.endInvocation);
       return eventActions;
     }

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

@@ -109,6 +109,9 @@ private ImmutableList<Content> getContents(
       if (!isEventBelongsToBranch(currentBranch, event)) {
         continue;
       }
+      if (isRequestConfirmationEvent(event)) {
+        continue;
+      }
 
       // TODO: Skip auth events.
 
@@ -511,4 +514,19 @@ private static boolean hasContentWithNonEmptyParts(Event event) {
         .map(list -> !list.isEmpty()) // Optional<Boolean>
         .orElse(false);
   }
+
+  /** Checks if the event is a request confirmation event. */
+  private static boolean isRequestConfirmationEvent(Event event) {
+    return event.content().flatMap(Content::parts).orElse(ImmutableList.of()).stream()
+        .anyMatch(
+            part ->
+                part.functionCall()
+                        .flatMap(FunctionCall::name)
+                        .map(name -> name.equals(Functions.REQUEST_CONFIRMATION_FUNCTION_CALL_NAME))
+                        .orElse(false)
+                    || part.functionResponse()
+                        .flatMap(FunctionResponse::name)
+                        .map(name -> name.equals(Functions.REQUEST_CONFIRMATION_FUNCTION_CALL_NAME))
+                        .orElse(false));
+  }
 }

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

@@ -17,6 +17,8 @@
 
 package com.google.adk.flows.llmflows;
 
+import static com.google.common.collect.ImmutableMap.toImmutableMap;
+
 import com.google.adk.Telemetry;
 import com.google.adk.agents.ActiveStreamingTool;
 import com.google.adk.agents.Callbacks.AfterToolCallback;
@@ -27,6 +29,7 @@
 import com.google.adk.events.EventActions;
 import com.google.adk.tools.BaseTool;
 import com.google.adk.tools.FunctionTool;
+import com.google.adk.tools.ToolConfirmation;
 import com.google.adk.tools.ToolContext;
 import com.google.common.base.VerifyException;
 import com.google.common.collect.ImmutableList;
@@ -59,6 +62,7 @@
 public final class Functions {
 
   private static final String AF_FUNCTION_CALL_ID_PREFIX = "adk-";
+  public static final String REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation";
   private static final Logger logger = LoggerFactory.getLogger(Functions.class);
 
   /** Generates a unique ID for a function call. */
@@ -121,6 +125,15 @@ 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, null);
+  }
+
+  /** Handles standard, non-streaming function calls with tool confirmations. */
+  public static Maybe<Event> handleFunctionCalls(
+      InvocationContext invocationContext,
+      Event functionCallEvent,
+      Map<String, BaseTool> tools,
+      @Nullable Map<String, ToolConfirmation> toolConfirmations) {
     ImmutableList<FunctionCall> functionCalls = functionCallEvent.functionCalls();
 
     List<Maybe<Event>> functionResponseEvents = new ArrayList<>();
@@ -133,6 +146,10 @@ public static Maybe<Event> handleFunctionCalls(
       ToolContext toolContext =
           ToolContext.builder(invocationContext)
               .functionCallId(functionCall.id().orElse(""))
+              .toolConfirmation(
+                  toolConfirmations != null
+                      ? toolConfirmations.get(functionCall.id().orElse(null))
+                      : null)
               .build();
 
       Map<String, Object> functionArgs = functionCall.args().orElse(new HashMap<>());
@@ -553,5 +570,65 @@ private static Event buildResponseEvent(
     }
   }
 
+  /**
+   * Generates a request confirmation event from a function response event.
+   *
+   * @param invocationContext The invocation context.
+   * @param functionCallEvent The event containing the original function call.
+   * @param functionResponseEvent The event containing the function response.
+   * @return An optional event containing the request confirmation function call.
+   */
+  public static Optional<Event> generateRequestConfirmationEvent(
+      InvocationContext invocationContext, Event functionCallEvent, Event functionResponseEvent) {
+    if (functionResponseEvent.actions().requestedToolConfirmations().isEmpty()) {
+      return Optional.empty();
+    }
+
+    List<Part> parts = new ArrayList<>();
+    Set<String> longRunningToolIds = new HashSet<>();
+    ImmutableMap<String, FunctionCall> functionCallsById =
+        functionCallEvent.functionCalls().stream()
+            .filter(fc -> fc.id().isPresent())
+            .collect(toImmutableMap(fc -> fc.id().get(), fc -> fc));
+
+    for (Map.Entry<String, ToolConfirmation> entry :
+        functionResponseEvent.actions().requestedToolConfirmations().entrySet().stream()
+            .filter(fc -> functionCallsById.containsKey(fc.getKey()))
+            .collect(toImmutableMap(Map.Entry::getKey, Map.Entry::getValue))
+            .entrySet()) {
+
+      FunctionCall requestConfirmationFunctionCall =
+          FunctionCall.builder()
+              .name(REQUEST_CONFIRMATION_FUNCTION_CALL_NAME)
+              .args(
+                  ImmutableMap.of(
+                      "originalFunctionCall",
+                      functionCallsById.get(entry.getKey()),
+                      "toolConfirmation",
+                      entry.getValue()))
+              .id(generateClientFunctionCallId())
+              .build();
+
+      longRunningToolIds.add(requestConfirmationFunctionCall.id().get());
+      parts.add(Part.builder().functionCall(requestConfirmationFunctionCall).build());
+    }
+
+    if (parts.isEmpty()) {
+      return Optional.empty();
+    }
+
+    var contentBuilder = Content.builder().parts(parts);
+    functionResponseEvent.content().flatMap(Content::role).ifPresent(contentBuilder::role);
+
+    return Optional.of(
+        Event.builder()
+            .invocationId(invocationContext.invocationId())
+            .author(invocationContext.agent().name())
+            .branch(invocationContext.branch())
+            .content(contentBuilder.build())
+            .longRunningToolIds(longRunningToolIds)
+            .build());
+  }
+
   private Functions() {}
 }