human_in_loop samples: reimburse runs without an approval; the model can call it first or after a rejection #7987

--- a/contributing/samples/hitl/human_in_loop/agent.py
+++ b/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,6 +39,19 @@
   }
 
 
+def needs_manager_approval(purpose: str, amount: float) -> bool:
+  """Holds reimburse() for confirmation when the amount needs a manager.
+
+  The instruction asks the model to call ask_for_approval() first, but nothing
+  makes the model do so: it can call reimburse() right away, or after the
+  manager rejected the ticket. With this predicate the framework pauses every
+  reimburse() call of $100 or more (adk_request_confirmation) until the
+  application confirms it, and the application confirms only a ticket the
+  manager approved (see main.py).
+  """
+  return amount >= 100
+
+
 root_agent = Agent(
     name='reimbursement_agent',
     instruction="""
@@ -50,6 +64,9 @@
       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),
 )
--- a/contributing/samples/hitl/human_in_loop/main.py
+++ b/contributing/samples/hitl/human_in_loop/main.py
@@ -23,6 +23,7 @@
 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 +49,47 @@
       session_service=session_service,
   )
 
+  async def answer_confirmation(
+      confirmation_call: types.FunctionCall, manager_approved: bool
+  ):
+    """Answers the framework's pause on reimburse() (adk_request_confirmation).
+
+    reimburse() is gated with require_confirmation, so a call the manager did
+    not approve is held here and rejected; only an approved ticket lets it run.
+    """
+    print(
+        f"--- Framework asks to confirm reimburse() (call ID"
+        f" {confirmation_call.id}); manager approved: {manager_approved} ---"
+    )
+    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=manager_approved
+                        ).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 +103,7 @@
     long_running_function_call: types.FunctionCall | None = None
     initial_tool_response: types.FunctionResponse | None = None
     ticket_id: str | None = None
+    confirmation_call: types.FunctionCall | None = None
 
     async for event in events_async:
       if event.content and event.content.parts:
@@ -73,7 +116,9 @@
                 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_call = 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 +147,11 @@
 
     print("--- End of agent's initial turn ---\n")
 
+    if confirmation_call:
+      # The model called reimburse() for an amount that needs a manager
+      # without an approved ticket: reject the held call.
+      await answer_confirmation(confirmation_call, manager_approved=False)
+
     if (
         long_running_function_call
         and initial_tool_response
@@ -131,6 +181,7 @@
       )
       print("--- Running agent's turn AFTER receiving updated tool result ---")
 
+      confirmation_call = None
       async for event in runner.run_async(
           session_id=session.id,
           user_id=USER_ID,
@@ -148,6 +199,8 @@
                   f" {part.function_call.name}({part.function_call.args}) ID:"
                   f" {part.function_call.id}"
               )
+              if part.function_call.name == "adk_request_confirmation":
+                confirmation_call = part.function_call
             if part.function_response:
               print(
                   f"    Part {i} [FunctionResponse]: For"
@@ -155,6 +208,12 @@
                   f" {part.function_response.id}, Response:"
                   f" {part.function_response.response}"
               )
+      if confirmation_call:
+        # The manager approved this ticket: let the held reimburse() run.
+        await answer_confirmation(
+            confirmation_call,
+            manager_approved=updated_tool_output_data["status"] == "approved",
+        )
       print("--- End of agent's turn AFTER receiving updated tool result ---")
 
     elif long_running_function_call and not initial_tool_response:
--- a/contributing/samples/hitl/human_in_loop/README.md
+++ b/contributing/samples/hitl/human_in_loop/README.md
@@ -47,4 +47,6 @@
 
 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 Payout**: `reimburse` is wrapped in `FunctionTool(reimburse, require_confirmation=needs_manager_approval)`, so the framework holds every `reimburse` call of $100 or more and emits an `adk_request_confirmation` call instead of running it. Your application answers that call with a `ToolConfirmation` (`confirmed=True` only when the manager approved the ticket, see `answer_confirmation` in `main.py`), and only then does `reimburse` run. The instruction alone does not enforce the order of the two tools: without this gate the model can call `reimburse` before `ask_for_approval`, or after a rejection, and the payout goes through.
+
 **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.
--- a/contributing/samples/hitl/tool_human_in_the_loop_config/tools.py
+++ b/contributing/samples/hitl/tool_human_in_the_loop_config/tools.py
@@ -17,8 +17,25 @@
 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."""
+  # The instruction asks the model to call ask_for_approval() first, but
+  # nothing makes the model do so. Amounts that need a manager are held here
+  # with the framework's confirmation flow until the application confirms the
+  # call, which it does only for a ticket the manager approved. The check is
+  # inside the tool because `FunctionTool.from_config` does not map a
+  # `require_confirmation` arg from YAML (it logs "Unsupported parsing" and
+  # builds the tool without it).
+  if amount >= 100:
+    if not tool_context.tool_confirmation:
+      tool_context.request_confirmation(
+          hint=f'Confirm the reimbursement of ${amount} for {purpose}.',
+      )
+      return {'error': 'This reimbursement needs the manager\'s approval.'}
+    if not tool_context.tool_confirmation.confirmed:
+      return {'error': 'The reimbursement was rejected.'}
   return {
       'status': 'ok',
   }