fix: fix long running tool docs (#229)

Co-authored-by: Sean Zhou <[email protected]>

Author: seanzhou1023

docs/tools/function-tools.md

@@ -58,62 +58,111 @@ While you have considerable flexibility in defining your function, remember that
 
 Designed for tasks that require a significant amount of processing time without blocking the agent's execution. This tool is a subclass of `FunctionTool`.
 
-When using a `LongRunningFunctionTool`, your Python function can initiate the long-running operation and optionally return an **intermediate result** to keep the model and user informed about the progress. The agent can then continue with other tasks. An example is the human-in-the-loop scenario where the agent needs human approval before proceeding with a task.
+When using a `LongRunningFunctionTool`, your Python function can initiate the long-running operation and optionally return an **initial result**** (e.g. the long-running operation id). Once a long running function tool is invoked the agent runner will pause the agent run and let the agent client to decide whether to continue or wait until the long-running operation finishes. The agent client can query the progress of the long-running operation and send back an intermediate or final response. The agent can then continue with other tasks. An example is the human-in-the-loop scenario where the agent needs human approval before proceeding with a task.
 
 ### How it Works
 
-You wrap a Python *generator* function (a function using `yield`) with `LongRunningFunctionTool`.
+You wrap a Python function with LongRunningFunctionTool.
 
-1. **Initiation:** When the LLM calls the tool, your generator function starts executing.
+1. **Initiation:** When the LLM calls the tool, your python function starts the long-running operation.
 
-2. **Intermediate Updates (`yield`):** Your function should yield intermediate Python objects (typically dictionaries) periodically to report progress. The ADK framework takes each yielded value and sends it back to the LLM packaged within a `FunctionResponse`. This allows the LLM to inform the user (e.g., status, percentage complete, messages).
+2. **Initial Updates:** Your function should optionally return an initial result (e.g. the long-running operaiton id). The ADK framework takes the result and sends it back to the LLM packaged within a `FunctionResponse`. This allows the LLM to inform the user (e.g., status, percentage complete, messages). And then the agent run is ended / paused.
 
-3. **Completion (`return`):** When the task is finished, the generator function uses `return` to provide the final Python object result.
+3. **Continue or Wait:** After each agent run is completed. Agent client can query the progress of the long-running operation and decide whether to continue the agent run with an intermediate response (to update the progress) or wait until a final response is retrieved. Agent client should send the intermediate or final response back to the agent for the next run.
 
-4. **Framework Handling:** The ADK framework manages the execution. It sends each yielded value back as an intermediate `FunctionResponse`. When the generator completes, the framework sends the returned value as the content of the final `FunctionResponse`, signaling the end of the long-running operation to the LLM.
+4. **Framework Handling:** The ADK framework manages the execution. It sends the intermediate or final `FunctionResponse` sent by agent client to the LLM to generate a user friendly message.
 
 ### Creating the Tool
 
-Define your generator function and wrap it using the `LongRunningFunctionTool` class:
+Define your tool function and wrap it using the `LongRunningFunctionTool` class:
 
 ```py
 from google.adk.tools import LongRunningFunctionTool
 
-# Define your generator function (see example below)
-def my_long_task_generator(*args, **kwargs):
-    # ... setup ...
-    yield {"status": "pending", "message": "Starting task..."} # Framework sends this as FunctionResponse
-    # ... perform work incrementally ...
-    yield {"status": "pending", "progress": 50}               # Framework sends this as FunctionResponse
-    # ... finish work ...
-    return {"status": "completed", "result": "Final outcome"} # Framework sends this as final FunctionResponse
+# Define your long running function (see example below)
+def ask_for_approval(
+    purpose: str, amount: float, tool_context: ToolContext
+) -> dict[str, Any]:
+  """Ask for approval for the reimbursement."""
+  # create a ticket for the approval
+  # Send a notification to the approver with the link of the ticket
+  return {'status': 'pending', 'approver': 'Sean Zhou', 'purpose' : purpose, 'amount': amount, 'ticket-id': 'approval-ticket-1'}
 
 # Wrap the function
-my_tool = LongRunningFunctionTool(func=my_long_task_generator)
+approve_tool = LongRunningFunctionTool(func=ask_for_approval)
 ```
 
-### Intermediate Updates
+### Intermediate / Final result Updates
 
-Yielding structured Python objects (like dictionaries) is crucial for providing meaningful updates. Include keys like:
+Agent client received an event with long running function calls and check the status of the ticket. Then Agent client can send the intermediate or final response back to update the progress. The framework packages this value (even if it's None) into the content of the `FunctionResponse` sent back to the LLM.
 
-* status: e.g., "pending", "running", "waiting_for_input"
-
-* progress: e.g., percentage, steps completed
-
-* message: Descriptive text for the user/LLM
-
-* estimated_completion_time: If calculable
-
-Each value you yield is packaged into a FunctionResponse by the framework and sent to the LLM.
-
-### Final Result
+```py
+# runner = Runner(...)
+# session = session_service.create_session(...)
+# content = types.Content(...) # User's initial query
+
+def get_long_running_function_call(event: Event) -> types.FunctionCall:
+    # Get the long running function call from the event
+    if not event.long_running_tool_ids or not event.content or not event.content.parts:
+        return
+    for part in event.content.parts:
+        if (
+            part 
+            and part.function_call 
+            and event.long_running_tool_ids 
+            and part.function_call.id in event.long_running_tool_ids
+        ):
+            return part.function_call
+
+def get_function_response(event: Event, function_call_id: str) -> types.FunctionResponse:
+    # Get the function response for the fuction call with specified id.
+    if not event.content or not event.content.parts:
+        return
+    for part in event.content.parts:
+        if (
+            part 
+            and part.function_response
+            and part.function_response.id == function_call_id
+        ):
+            return part.function_response
+
+print("\nRunning agent...")
+events_async = runner.run_async(
+    session_id=session.id, user_id='user', new_message=content
+)
+
+
+long_running_function_call, long_running_function_response, ticket_id = None, None, None
+async for event in events_async:
+    # Use helper to check for the specific auth request event
+    if not long_running_function_call:
+        long_running_function_call = get_long_running_function_call(event)
+    else:
+        long_running_function_response = get_function_response(event, long_running_function_call.id)
+        if long_running_function_response:
+            ticket_id = long_running_function_response.response['ticket_id']
+    if event.content and event.content.parts:
+        if text := ''.join(part.text or '' for part in event.content.parts):
+            print(f'[{event.author}]: {text}')
+
+    if long_running_function_response:
+        # query the status of the correpsonding ticket via tciket_id
+        # send back an intermediate / final response
+        updated_response = long_running_function_response.model_copy(deep=True)
+        updated_response.response = {'status': 'approved'}
+        async for event in runner.run_async(
+          session_id=session.id, user_id='user', new_message=types.Content(parts=[types.Part(function_response = updated_response)], role='user')
+        ):
+            if event.content and event.content.parts:
+                if text := ''.join(part.text or '' for part in event.content.parts):
+                    print(f'[{event.author}]: {text}')   
+```
 
-The Python object your generator function returns is considered the final result of the tool execution. The framework packages this value (even if it's None) into the content of the final `FunctionResponse` sent back to the LLM, indicating the tool execution is complete.
 
 ??? "Example: File Processing Simulation"
 
     ```py
-    --8<-- "examples/python/snippets/tools/function-tools/file_processor.py"
+    --8<-- "examples/python/snippets/tools/function-tools/human_in_the_loop.py"
     ```
 
 #### Key aspects of this example
@@ -166,3 +215,4 @@ The `AgentTool` class provides the following attributes for customizing its beha
 4. The `summary_agent` will process the text according to its instruction and generate a summary.  
 5. **The response from the `summary_agent` is then passed back to the `main_agent`.**  
 6. The `main_agent` can then take the summary and formulate its final response to the user (e.g., "Here's a summary of the text: ...")
+

examples/python/snippets/tools/function-tools/file_processor.py

@@ -0,0 +1,136 @@
+# Copyright 2025 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.
+
+import asyncio
+from typing import Any
+from google.adk.agents import Agent
+from google.adk.events import Event
+from google.adk.runners import Runner
+from google.adk.tools import LongRunningFunctionTool
+from google.adk.sessions import InMemorySessionService
+from google.genai import types
+
+# 1. Define the long running function
+def ask_for_approval(
+    purpose: str, amount: float
+) -> dict[str, Any]:
+    """Ask for approval for the reimbursement."""
+    # create a ticket for the approval
+    # Send a notification to the approver with the link of the ticket
+    return {'status': 'pending', 'approver': 'Sean Zhou', 'purpose' : purpose, 'amount': amount, 'ticket-id': 'approval-ticket-1'}
+
+def reimburse(purpose: str, amount: float) -> str:
+    """Reimburse the amount of money to the employee."""
+    # send the reimbrusement request to payment vendor
+    return {'status': 'ok'}
+
+# 2. Wrap the function with LongRunningFunctionTool
+long_running_tool = LongRunningFunctionTool(func=ask_for_approval)
+
+# 3. Use the tool in an Agent
+file_processor_agent = Agent(
+    # Use a model compatible with function calling
+    model="gemini-2.0-flash",
+    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
+      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, long_running_tool]
+)
+
+
+APP_NAME = "human_in_the_loop"
+USER_ID = "1234"
+SESSION_ID = "session1234"
+
+# Session and Runner
+session_service = InMemorySessionService()
+session = session_service.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID)
+runner = Runner(agent=file_processor_agent, app_name=APP_NAME, session_service=session_service)
+
+
+# Agent Interaction
+async def call_agent(query):
+
+    def get_long_running_function_call(event: Event) -> types.FunctionCall:
+        # Get the long running function call from the event
+        if not event.long_running_tool_ids or not event.content or not event.content.parts:
+            return
+        for part in event.content.parts:
+            if (
+                part
+                and part.function_call
+                and event.long_running_tool_ids
+                and part.function_call.id in event.long_running_tool_ids
+            ):
+                return part.function_call
+
+    def get_function_response(event: Event, function_call_id: str) -> types.FunctionResponse:
+        # Get the function response for the fuction call with specified id.
+        if not event.content or not event.content.parts:
+            return
+        for part in event.content.parts:
+            if (
+                part
+                and part.function_response
+                and part.function_response.id == function_call_id
+            ):
+                return part.function_response
+
+    content = types.Content(role='user', parts=[types.Part(text=query)])
+    events = runner.run_async(user_id=USER_ID, session_id=SESSION_ID, new_message=content)
+
+    print("\nRunning agent...")
+    events_async = runner.run_async(
+        session_id=session.id, user_id='user', new_message=content
+    )
+
+
+    long_running_function_call, long_running_function_response, ticket_id = None, None, None
+    async for event in events_async:
+        # Use helper to check for the specific auth request event
+        if not long_running_function_call:
+            long_running_function_call = get_long_running_function_call(event)
+        else:
+            long_running_function_response = get_function_response(event, long_running_function_call.id)
+            if long_running_function_response:
+                ticket_id = long_running_function_response.response['ticket_id']
+        if event.content and event.content.parts:
+            if text := ''.join(part.text or '' for part in event.content.parts):
+                print(f'[{event.author}]: {text}')
+
+
+    if long_running_function_response:
+        # query the status of the correpsonding ticket via tciket_id
+        # send back an intermediate / final response
+        updated_response = long_running_function_response.model_copy(deep=True)
+        updated_response.response = {'status': 'approved'}
+        async for event in runner.run_async(
+          session_id=session.id, user_id='user', new_message=types.Content(parts=[types.Part(function_response = updated_response)], role='user')
+        ):
+            if event.content and event.content.parts:
+                if text := ''.join(part.text or '' for part in event.content.parts):
+                    print(f'[{event.author}]: {text}')
+
+# reimbursement that doesn't require approval
+asyncio.run(call_agent("Please reimburse 50$ for meals"))
+# reimbursement that requires approval
+asyncio.run(call_agent("Please reimburse 200$ for meals"))