feat(runner): add metadata parameter to run(), run_live(), run_debug()

Add metadata support to all run methods for consistency:
- run(): sync wrapper, passes metadata to run_async()
- run_live(): live mode, passes metadata through invocation context
- run_debug(): debug helper, passes metadata to run_async()

Also update InvocationContext docstring to reflect all supported entry points.

Author: donggyun112

src/google/adk/agents/invocation_context.py

@@ -207,12 +207,14 @@ class InvocationContext(BaseModel):
   """The cache of canonical tools for this invocation."""
 
   metadata: Optional[dict[str, Any]] = None
-  """Per-request metadata passed from Runner.run_async().
+  """Per-request metadata passed from Runner entry points.
 
   This field allows passing arbitrary metadata that can be accessed during
   the invocation lifecycle, particularly in callbacks like before_model_callback.
   Common use cases include passing user_id, trace_id, memory context keys, or
   other request-specific context that needs to be available during processing.
+
+  Supported entry points: run(), run_async(), run_live(), run_debug().
   """
 
   _invocation_cost_manager: _InvocationCostManager = PrivateAttr(

src/google/adk/runners.py

@@ -390,6 +390,7 @@ def run(
       session_id: str,
       new_message: types.Content,
       run_config: Optional[RunConfig] = None,
+      metadata: Optional[dict[str, Any]] = None,
   ) -> Generator[Event, None, None]:
     """Runs the agent.
 
@@ -407,6 +408,7 @@ def run(
       session_id: The session ID of the session.
       new_message: A new message to append to the session.
       run_config: The run config for the agent.
+      metadata: Optional per-request metadata that will be passed to callbacks.
 
     Yields:
       The events generated by the agent.
@@ -422,6 +424,7 @@ async def _invoke_run_async():
                 session_id=session_id,
                 new_message=new_message,
                 run_config=run_config,
+                metadata=metadata,
             )
         ) as agen:
           async for event in agen:
@@ -941,6 +944,7 @@ async def run_live(
       live_request_queue: LiveRequestQueue,
       run_config: Optional[RunConfig] = None,
       session: Optional[Session] = None,
+      metadata: Optional[dict[str, Any]] = None,
   ) -> AsyncGenerator[Event, None]:
     """Runs the agent in live mode (experimental feature).
 
@@ -982,6 +986,7 @@ async def run_live(
         run_config: The run config for the agent.
         session: The session to use. This parameter is deprecated, please use
           `user_id` and `session_id` instead.
+        metadata: Optional per-request metadata that will be passed to callbacks.
 
     Yields:
         AsyncGenerator[Event, None]: An asynchronous generator that yields
@@ -996,6 +1001,7 @@ async def run_live(
         Either `session` or both `user_id` and `session_id` must be provided.
     """
     run_config = run_config or RunConfig()
+    metadata = metadata.copy() if metadata is not None else None
     # Some native audio models requires the modality to be set. So we set it to
     # AUDIO by default.
     if run_config.response_modalities is None:
@@ -1021,6 +1027,7 @@ async def run_live(
         session,
         live_request_queue=live_request_queue,
         run_config=run_config,
+        metadata=metadata,
     )
 
     root_agent = self.agent
@@ -1127,6 +1134,7 @@ async def run_debug(
       run_config: RunConfig | None = None,
       quiet: bool = False,
       verbose: bool = False,
+      metadata: dict[str, Any] | None = None,
   ) -> list[Event]:
     """Debug helper for quick agent experimentation and testing.
 
@@ -1150,6 +1158,7 @@ async def run_debug(
           shown).
         verbose: If True, shows detailed tool calls and responses. Defaults to
           False for cleaner output showing only final agent responses.
+        metadata: Optional per-request metadata that will be passed to callbacks.
 
     Returns:
         list[Event]: All events from all messages.
@@ -1212,6 +1221,7 @@ async def run_debug(
           session_id=session.id,
           new_message=types.UserContent(parts=[types.Part(text=message)]),
           run_config=run_config,
+          metadata=metadata,
       ):
         if not quiet:
           print_event(event, verbose=verbose)
@@ -1401,6 +1411,7 @@ def _new_invocation_context_for_live(
       *,
       live_request_queue: LiveRequestQueue,
       run_config: Optional[RunConfig] = None,
+      metadata: Optional[dict[str, Any]] = None,
   ) -> InvocationContext:
     """Creates a new invocation context for live multi-agent."""
     run_config = run_config or RunConfig()
@@ -1419,6 +1430,7 @@ def _new_invocation_context_for_live(
         session,
         live_request_queue=live_request_queue,
         run_config=run_config,
+        metadata=metadata,
     )
 
   async def _handle_new_message(

tests/unittests/test_runners.py

@@ -22,6 +22,7 @@
 
 from google.adk.agents.base_agent import BaseAgent
 from google.adk.agents.context_cache_config import ContextCacheConfig
+from google.adk.agents.live_request_queue import LiveRequestQueue
 from google.adk.agents.invocation_context import InvocationContext
 from google.adk.agents.llm_agent import LlmAgent
 from google.adk.agents.run_config import RunConfig
@@ -35,6 +36,7 @@
 from google.adk.plugins.base_plugin import BasePlugin
 from google.adk.runners import Runner
 from google.adk.sessions.in_memory_session_service import InMemorySessionService
+from tests.unittests import testing_utils
 from google.adk.sessions.session import Session
 from google.genai import types
 import pytest
@@ -1483,6 +1485,125 @@ def before_model_callback(callback_context, llm_request):
     # Nested object changes in callback WILL affect original (shallow copy behavior)
     assert original_metadata["nested"]["inner_key"] == "modified_nested"
 
+  def test_new_invocation_context_for_live_with_metadata(self):
+    """Test that _new_invocation_context_for_live correctly passes metadata."""
+    mock_session = Session(
+        id=TEST_SESSION_ID,
+        app_name=TEST_APP_ID,
+        user_id=TEST_USER_ID,
+        events=[],
+    )
+
+    test_metadata = {"user_id": "live_user", "trace_id": "live_trace"}
+    invocation_context = self.runner._new_invocation_context_for_live(
+        mock_session, metadata=test_metadata
+    )
+
+    assert invocation_context.metadata == test_metadata
+    assert invocation_context.metadata["user_id"] == "live_user"
+
+  @pytest.mark.asyncio
+  async def test_run_sync_passes_metadata(self):
+    """Test that sync run() correctly passes metadata to run_async()."""
+    captured_metadata = None
+
+    def before_model_callback(callback_context, llm_request):
+      nonlocal captured_metadata
+      captured_metadata = llm_request.metadata
+      return LlmResponse(
+          content=types.Content(
+              role="model", parts=[types.Part(text="Test response")]
+          )
+      )
+
+    agent_with_callback = LlmAgent(
+        name="callback_agent",
+        model="gemini-2.0-flash",
+        before_model_callback=before_model_callback,
+    )
+
+    runner_with_callback = Runner(
+        app_name="test_app",
+        agent=agent_with_callback,
+        session_service=self.session_service,
+        artifact_service=self.artifact_service,
+    )
+
+    await self.session_service.create_session(
+        app_name=TEST_APP_ID, user_id=TEST_USER_ID, session_id=TEST_SESSION_ID
+    )
+
+    test_metadata = {"sync_key": "sync_value"}
+
+    for event in runner_with_callback.run(
+        user_id=TEST_USER_ID,
+        session_id=TEST_SESSION_ID,
+        new_message=types.Content(
+            role="user", parts=[types.Part(text="Hello")]
+        ),
+        metadata=test_metadata,
+    ):
+      pass
+
+    assert captured_metadata is not None
+    assert captured_metadata["sync_key"] == "sync_value"
+
+  @pytest.mark.asyncio
+  async def test_run_live_passes_metadata_to_llm_request(self):
+    """Test that run_live() passes metadata through live pipeline to LlmRequest."""
+    import asyncio
+
+    # Create MockModel to capture LlmRequest
+    mock_model = testing_utils.MockModel.create(
+        responses=[
+            LlmResponse(
+                content=types.Content(
+                    role="model", parts=[types.Part(text="Live response")]
+                )
+            )
+        ]
+    )
+
+    agent_with_mock = LlmAgent(
+        name="live_mock_agent",
+        model=mock_model,
+    )
+
+    runner_with_mock = Runner(
+        app_name="test_app",
+        agent=agent_with_mock,
+        session_service=self.session_service,
+        artifact_service=self.artifact_service,
+    )
+
+    await self.session_service.create_session(
+        app_name=TEST_APP_ID, user_id=TEST_USER_ID, session_id=TEST_SESSION_ID
+    )
+
+    test_metadata = {"live_key": "live_value", "trace_id": "live_trace_123"}
+    live_queue = LiveRequestQueue()
+    live_queue.close()  # Close immediately to end the live session
+
+    async def consume_events():
+      async for event in runner_with_mock.run_live(
+          user_id=TEST_USER_ID,
+          session_id=TEST_SESSION_ID,
+          live_request_queue=live_queue,
+          metadata=test_metadata,
+      ):
+        pass
+
+    try:
+      await asyncio.wait_for(consume_events(), timeout=2)
+    except asyncio.TimeoutError:
+      pass  # Expected - live session may not terminate cleanly
+
+    # Verify MockModel received LlmRequest with correct metadata
+    assert len(mock_model.requests) > 0
+    assert mock_model.requests[0].metadata is not None
+    assert mock_model.requests[0].metadata["live_key"] == "live_value"
+    assert mock_model.requests[0].metadata["trace_id"] == "live_trace_123"
+
 
 if __name__ == "__main__":
   pytest.main([__file__])