fix: require confirmation before large reimbursements in hitl samples

Merge #7993

In the human_in_loop and tool_human_in_the_loop_config samples, reimburse
calls of $100 or more now pause for a tool confirmation instead of running
whenever the model calls them. The YAML sample's reimburse tool now takes a
tool_context. The A2A human-in-the-loop sample is unchanged.

Part of #7987

PiperOrigin-RevId: 1015684580

Author: trackoor

contributing/samples/hitl/human_in_loop/README.md

@@ -47,4 +47,6 @@ This example demonstrates an agent using a long-running tool (`ask_for_approval`
 
 1. **Agent Acts on Update**: The agent receives this message containing the `types.FunctionResponse` and, based on its instructions, proceeds with the next steps (e.g., calling another tool like `reimburse`).
 
+1. **Application Confirms the Reimbursement**: For amounts of $100 or more, `FunctionTool(require_confirmation=needs_manager_approval)` holds `reimburse` and emits `adk_request_confirmation`. The application answers with a `FunctionResponse` using that confirmation call's `id` and `name`, with a `ToolConfirmation` payload. In `main.py`, `answer_confirmations` confirms at most one call matching the approved ticket's amount and purpose (purpose compared ignoring case and surrounding whitespace); calls without approval are rejected. The instruction and the updated approval response alone do not authorize a reimbursement. The YAML sibling, `tool_human_in_the_loop_config`, gates the same call with `tool_context.request_confirmation()` inside `reimburse` instead, because `AgentConfig` YAML cannot express `require_confirmation` yet.
+
 **Why is this important?** The agent relies on receiving this subsequent `types.FunctionResponse` (provided in a message with `role="user"` containing the specific `Part`) to understand that the long-running task has concluded or its state has changed. Without it, the agent will remain unaware of the outcome of the pending task.

contributing/samples/hitl/human_in_loop/agent.py

@@ -15,6 +15,7 @@
 from typing import Any
 
 from google.adk import Agent
+from google.adk.tools.function_tool import FunctionTool
 from google.adk.tools.long_running_tool import LongRunningFunctionTool
 from google.adk.tools.tool_context import ToolContext
 from google.genai import types
@@ -38,18 +39,26 @@ def ask_for_approval(
   }
 
 
+def needs_manager_approval(purpose: str, amount: float) -> bool:
+  """Require manager approval for reimbursements of $100 or more."""
+  return amount >= 100
+
+
 root_agent = Agent(
     name='reimbursement_agent',
     instruction="""
       You are an agent whose job is to handle the reimbursement process for
       the employees. If the amount is less than $100, you will automatically
       approve the reimbursement.
 
-      If the amount is greater than $100, you will
+      If the amount is at least $100, you will
       ask for approval from the manager. If the manager approves, you will
       call reimburse() to reimburse the amount to the employee. If the manager
       rejects, you will inform the employee of the rejection.
 """,
-    tools=[reimburse, LongRunningFunctionTool(func=ask_for_approval)],
+    tools=[
+        FunctionTool(reimburse, require_confirmation=needs_manager_approval),
+        LongRunningFunctionTool(func=ask_for_approval),
+    ],
     generate_content_config=types.GenerateContentConfig(temperature=0.1),
 )

contributing/samples/hitl/human_in_loop/main.py

@@ -18,11 +18,9 @@
 
 import agent
 from dotenv import load_dotenv
-from google.adk.agents.llm_agent import Agent
-from google.adk.events.event import Event
 from google.adk.runners import Runner
 from google.adk.sessions.in_memory_session_service import InMemorySessionService
-from google.adk.tools.long_running_tool import LongRunningFunctionTool
+from google.adk.tools.tool_confirmation import ToolConfirmation
 from google.genai import types
 from opentelemetry import trace
 from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter
@@ -48,6 +46,57 @@ async def main():
       session_service=session_service,
   )
 
+  async def answer_confirmations(
+      confirmation_calls: list[types.FunctionCall],
+      *,
+      approved_args: dict[str, Any] | None = None,
+  ) -> None:
+    """Confirm at most one reimbursement matching the approved ticket."""
+    for confirmation_call in confirmation_calls:
+      original_call = (confirmation_call.args or {}).get(
+          "originalFunctionCall", {}
+      )
+      call_args = original_call.get("args") or {}
+      # Purpose is compared loosely so model wording drift does not reject it.
+      confirmed = (
+          approved_args is not None
+          and original_call.get("name") == "reimburse"
+          and call_args.get("amount") == approved_args.get("amount")
+          and str(call_args.get("purpose", "")).strip().lower()
+          == str(approved_args.get("purpose", "")).strip().lower()
+      )
+      if confirmed:
+        approved_args = None
+      print(f"--- Confirming reimbursement: {confirmed} ---")
+      async for event in runner.run_async(
+          session_id=session.id,
+          user_id=USER_ID,
+          new_message=types.Content(
+              role="user",
+              parts=[
+                  types.Part(
+                      function_response=types.FunctionResponse(
+                          id=confirmation_call.id,
+                          name=confirmation_call.name,
+                          response=ToolConfirmation(
+                              confirmed=confirmed
+                          ).model_dump(),
+                      )
+                  )
+              ],
+          ),
+      ):
+        if event.content and event.content.parts:
+          for i, part in enumerate(event.content.parts):
+            if part.text:
+              print(f"    Part {i} [Text]: {part.text.strip()}")
+            if part.function_response:
+              print(
+                  f"    Part {i} [FunctionResponse]: For"
+                  f" '{part.function_response.name}', Response:"
+                  f" {part.function_response.response}"
+              )
+
   async def call_agent(query: str):
     content = types.Content(role="user", parts=[types.Part(text=query)])
 
@@ -61,6 +110,7 @@ async def call_agent(query: str):
     long_running_function_call: types.FunctionCall | None = None
     initial_tool_response: types.FunctionResponse | None = None
     ticket_id: str | None = None
+    confirmation_calls: list[types.FunctionCall] = []
 
     async for event in events_async:
       if event.content and event.content.parts:
@@ -73,7 +123,9 @@ async def call_agent(query: str):
                 f" {part.function_call.name}({part.function_call.args}) ID:"
                 f" {part.function_call.id}"
             )
-            if not long_running_function_call and part.function_call.id in (
+            if part.function_call.name == "adk_request_confirmation":
+              confirmation_calls.append(part.function_call)
+            elif not long_running_function_call and part.function_call.id in (
                 event.long_running_tool_ids or []
             ):
               long_running_function_call = part.function_call
@@ -102,6 +154,9 @@ async def call_agent(query: str):
 
     print("--- End of agent's initial turn ---\n")
 
+    # No ticket has been approved yet, even if the model calls reimburse first.
+    await answer_confirmations(confirmation_calls)
+
     if (
         long_running_function_call
         and initial_tool_response
@@ -131,6 +186,7 @@ async def call_agent(query: str):
       )
       print("--- Running agent's turn AFTER receiving updated tool result ---")
 
+      confirmation_calls = []
       async for event in runner.run_async(
           session_id=session.id,
           user_id=USER_ID,
@@ -143,6 +199,8 @@ async def call_agent(query: str):
             if part.text:
               print(f"    Part {i} [Text]: {part.text.strip()}")
             if part.function_call:
+              if part.function_call.name == "adk_request_confirmation":
+                confirmation_calls.append(part.function_call)
               print(
                   f"    Part {i} [FunctionCall]:"
                   f" {part.function_call.name}({part.function_call.args}) ID:"
@@ -155,6 +213,14 @@ async def call_agent(query: str):
                   f" {part.function_response.id}, Response:"
                   f" {part.function_response.response}"
               )
+      await answer_confirmations(
+          confirmation_calls,
+          approved_args=(
+              long_running_function_call.args
+              if updated_tool_output_data["status"] == "approved"
+              else None
+          ),
+      )
       print("--- End of agent's turn AFTER receiving updated tool result ---")
 
     elif long_running_function_call and not initial_tool_response:

contributing/samples/hitl/human_in_loop/tests/reimburse_dinner.json

@@ -131,6 +131,95 @@
         "path": "reimbursement_agent@1"
       }
     },
+    {
+      "author": "reimbursement_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "originalFunctionCall": {
+                  "args": {
+                    "amount": 150,
+                    "purpose": "client dinner"
+                  },
+                  "id": "fc-2",
+                  "name": "reimburse"
+                },
+                "toolConfirmation": {
+                  "confirmed": false,
+                  "hint": "Please approve or reject the tool call reimburse() by responding with a FunctionResponse with an expected ToolConfirmation payload."
+                }
+              },
+              "id": "fc-3",
+              "name": "adk_request_confirmation"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "id": "e-7",
+      "invocationId": "i-2",
+      "longRunningToolIds": [
+        "fc-3"
+      ],
+      "nodeInfo": {
+        "path": "reimbursement_agent@1"
+      }
+    },
+    {
+      "actions": {
+        "requestedToolConfirmations": {
+          "fc-2": {
+            "confirmed": false,
+            "hint": "Please approve or reject the tool call reimburse() by responding with a FunctionResponse with an expected ToolConfirmation payload."
+          }
+        },
+        "skipSummarization": true
+      },
+      "author": "reimbursement_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-2",
+              "name": "reimburse",
+              "response": {
+                "error": "This tool call requires confirmation, please approve or reject."
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-8",
+      "invocationId": "i-2",
+      "nodeInfo": {
+        "path": "reimbursement_agent@1"
+      }
+    },
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-3",
+              "name": "adk_request_confirmation",
+              "response": {
+                "confirmed": true
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-9",
+      "invocationId": "i-2",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
     {
       "author": "reimbursement_agent",
       "content": {
@@ -147,7 +236,7 @@
         ],
         "role": "user"
       },
-      "id": "e-7",
+      "id": "e-10",
       "invocationId": "i-2",
       "nodeInfo": {
         "path": "reimbursement_agent@1"
@@ -164,7 +253,7 @@
         "role": "model"
       },
       "finishReason": "STOP",
-      "id": "e-8",
+      "id": "e-11",
       "invocationId": "i-2",
       "nodeInfo": {
         "path": "reimbursement_agent@1"

contributing/samples/hitl/tool_human_in_the_loop_config/root_agent.yaml

@@ -20,7 +20,7 @@ instruction: |
       the employees. If the amount is less than $100, you will automatically
       approve the reimbursement.
 
-      If the amount is greater than $100, you will
+      If the amount is at least $100, you will
       ask for approval from the manager. If the manager approves, you will
       call reimburse() to reimburse the amount to the employee. If the manager
       rejects, you will inform the employee of the rejection.

contributing/samples/hitl/tool_human_in_the_loop_config/tools.py

@@ -17,8 +17,19 @@
 from google.adk.tools.tool_context import ToolContext
 
 
-def reimburse(purpose: str, amount: float) -> dict[str, str]:
+def reimburse(
+    purpose: str, amount: float, tool_context: ToolContext
+) -> dict[str, str]:
   """Reimburse the amount of money to the employee."""
+  if amount >= 100:
+    if not tool_context.tool_confirmation:
+      tool_context.request_confirmation(
+          hint=f'Confirm the reimbursement of ${amount} for {purpose}.',
+      )
+      tool_context.actions.skip_summarization = True
+      return {'error': 'This reimbursement needs manager approval.'}
+    if not tool_context.tool_confirmation.confirmed:
+      return {'error': 'The reimbursement was rejected.'}
   return {
       'status': 'ok',
   }