fix: Use inspect.signature() instead of typing.get_type_hints

fix: Use `inspect.signature()` instead of `typing.get_type_hints()` to find the LiveRequestQueue.
Motivation: `typing.get_type_hints()` may raise errors in complex scenarios where type annotation is not available.

Add live_bidi_streaming_tools_agent example to show how to use the live streaming feature.

PiperOrigin-RevId: 780160921

Author: hangfei

contributing/samples/live_bidi_streaming_tools_agent/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+
+from . import agent

contributing/samples/live_bidi_streaming_tools_agent/agent.py

@@ -0,0 +1,140 @@
+# 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 AsyncGenerator
+
+from google.adk.agents import LiveRequestQueue
+from google.adk.agents.llm_agent import Agent
+from google.adk.tools.function_tool import FunctionTool
+from google.genai import Client
+from google.genai import types as genai_types
+
+
+async def monitor_stock_price(stock_symbol: str) -> AsyncGenerator[str, None]:
+  """This function will monitor the price for the given stock_symbol in a continuous, streaming and asynchronously way."""
+  print(f"Start monitor stock price for {stock_symbol}!")
+
+  # Let's mock stock price change.
+  await asyncio.sleep(4)
+  price_alert1 = f"the price for {stock_symbol} is 300"
+  yield price_alert1
+  print(price_alert1)
+
+  await asyncio.sleep(4)
+  price_alert1 = f"the price for {stock_symbol} is 400"
+  yield price_alert1
+  print(price_alert1)
+
+  await asyncio.sleep(20)
+  price_alert1 = f"the price for {stock_symbol} is 900"
+  yield price_alert1
+  print(price_alert1)
+
+  await asyncio.sleep(20)
+  price_alert1 = f"the price for {stock_symbol} is 500"
+  yield price_alert1
+  print(price_alert1)
+
+
+# for video streaming, `input_stream: LiveRequestQueue` is required and reserved key parameter for ADK to pass the video streams in.
+async def monitor_video_stream(
+    input_stream: LiveRequestQueue,
+) -> AsyncGenerator[str, None]:
+  """Monitor how many people are in the video streams."""
+  print("start monitor_video_stream!")
+  client = Client(vertexai=False)
+  prompt_text = (
+      "Count the number of people in this image. Just respond with a numeric"
+      " number."
+  )
+  last_count = None
+  while True:
+    last_valid_req = None
+    print("Start monitoring loop")
+
+    # use this loop to pull the latest images and discard the old ones
+    while input_stream._queue.qsize() != 0:
+      live_req = await input_stream.get()
+
+      if live_req.blob is not None and live_req.blob.mime_type == "image/jpeg":
+        last_valid_req = live_req
+
+    # If we found a valid image, process it
+    if last_valid_req is not None:
+      print("Processing the most recent frame from the queue")
+
+      # Create an image part using the blob's data and mime type
+      image_part = genai_types.Part.from_bytes(
+          data=last_valid_req.blob.data, mime_type=last_valid_req.blob.mime_type
+      )
+
+      contents = genai_types.Content(
+          role="user",
+          parts=[image_part, genai_types.Part.from_text(text=prompt_text)],
+      )
+
+      # Call the model to generate content based on the provided image and prompt
+      response = client.models.generate_content(
+          model="gemini-2.0-flash-exp",
+          contents=contents,
+          config=genai_types.GenerateContentConfig(
+              system_instruction=(
+                  "You are a helpful video analysis assistant. You can count"
+                  " the number of people in this image or video. Just respond"
+                  " with a numeric number."
+              )
+          ),
+      )
+      if not last_count:
+        last_count = response.candidates[0].content.parts[0].text
+      elif last_count != response.candidates[0].content.parts[0].text:
+        last_count = response.candidates[0].content.parts[0].text
+        yield response
+        print("response:", response)
+
+    # Wait before checking for new images
+    await asyncio.sleep(0.5)
+
+
+# Use this exact function to help ADK stop your streaming tools when requested.
+# for example, if we want to stop `monitor_stock_price`, then the agent will
+# invoke this function with stop_streaming(function_name=monitor_stock_price).
+def stop_streaming(function_name: str):
+  """Stop the streaming
+
+  Args:
+    function_name: The name of the streaming function to stop.
+  """
+  pass
+
+
+root_agent = Agent(
+    model="gemini-live-2.5-flash-preview",
+    name="video_streaming_agent",
+    instruction="""
+      You are a monitoring agent. You can do video monitoring and stock price monitoring
+      using the provided tools/functions.
+      When users want to monitor a video stream,
+      You can use monitor_video_stream function to do that. When monitor_video_stream
+      returns the alert, you should tell the users.
+      When users want to monitor a stock price, you can use monitor_stock_price.
+      Don't ask too many questions. Don't be too talkative.
+    """,
+    tools=[
+        monitor_video_stream,
+        monitor_stock_price,
+        FunctionTool(stop_streaming),
+    ],
+)

contributing/samples/live_bidi_streaming_tools_agent/readme.md

@@ -0,0 +1,19 @@
+ This is only supported in streaming(live) agents/api.
+
+Streaming tools allows tools(functions) to stream intermediate results back to agents and agents can respond to those intermediate results. 
+For example, we can use streaming tools to monitor the changes of the stock price and have the agent react to it. Another example is we can have the agent monitor the video stream, and when there is changes in video stream, the agent can report the changes.
+
+To define a streaming tool, you must adhere to the following:
+
+1.  **Asynchronous Function:** The tool must be an `async` Python function.
+2.  **AsyncGenerator Return Type:** The function must be typed to return an `AsyncGenerator`. The first type parameter to `AsyncGenerator` is the type of the data you `yield` (e.g., `str` for text messages, or a custom object for structured data). The second type parameter is typically `None` if the generator doesn't receive values via `send()`.
+
+
+We support two types of streaming tools:
+- Simple type. This is a one type of streaming tools that only take non video/audio streams(the streams that you feed to adk web or adk runner) as input.
+- Video streaming tools. This only works in video streaming and the video stream(the streams that you feed to adk web or adk runner) will be passed into this function.
+
+
+Here are some sample queries to test:
+- Help me monitor the stock price for $XYZ stock.
+- Help me monitor how many people are there in the video stream.

src/google/adk/runners.py

@@ -307,27 +307,44 @@ async def run_live(
     root_agent = self.agent
     invocation_context.agent = self._find_agent_to_run(session, root_agent)
 
+    # Pre-processing for live streaming tools
+    # Inspect the tool's parameters to find if it uses LiveRequestQueue
     invocation_context.active_streaming_tools = {}
     # TODO(hangfei): switch to use canonical_tools.
     # for shell agents, there is no tools associated with it so we should skip.
     if hasattr(invocation_context.agent, 'tools'):
-      for tool in invocation_context.agent.tools:
-        # replicate a LiveRequestQueue for streaming tools that relis on
-        # LiveRequestQueue
-        from typing import get_type_hints
+      import inspect
 
-        type_hints = get_type_hints(tool)
-        for arg_type in type_hints.values():
-          if arg_type is LiveRequestQueue:
+      for tool in invocation_context.agent.tools:
+        # We use `inspect.signature()` to examine the tool's underlying function (`tool.func`).
+        # This approach is deliberately chosen over `typing.get_type_hints()` for robustness.
+        #
+        # The Problem with `get_type_hints()`:
+        # `get_type_hints()` attempts to resolve forward-referenced (string-based) type
+        # annotations. This resolution can easily fail with a `NameError` (e.g., "Union not found")
+        # if the type isn't available in the scope where `get_type_hints()` is called.
+        # This is a common and brittle issue in framework code that inspects functions
+        # defined in separate user modules.
+        #
+        # Why `inspect.signature()` is Better Here:
+        # `inspect.signature()` does NOT resolve the annotations; it retrieves the raw
+        # annotation object as it was defined on the function. This allows us to
+        # perform a direct and reliable identity check (`param.annotation is LiveRequestQueue`)
+        # without risking a `NameError`.
+        callable_to_inspect = tool.func if hasattr(tool, 'func') else tool
+        # Ensure the target is actually callable before inspecting to avoid errors.
+        if not callable(callable_to_inspect):
+          continue
+        for param in inspect.signature(callable_to_inspect).parameters.values():
+          if param.annotation is LiveRequestQueue:
             if not invocation_context.active_streaming_tools:
               invocation_context.active_streaming_tools = {}
-            active_streaming_tools = ActiveStreamingTool(
+            active_streaming_tool = ActiveStreamingTool(
                 stream=LiveRequestQueue()
             )
             invocation_context.active_streaming_tools[tool.__name__] = (
-                active_streaming_tools
+                active_streaming_tool
             )
-
     async for event in invocation_context.agent.run_live(invocation_context):
       await self.session_service.append_event(session=session, event=event)
       yield event