feat: forward custom_metadata from run requests into the run config

Add a custom_metadata field to the /run and /run_sse request payloads
and forward it to the runner via RunConfig.custom_metadata, so callers
can attach arbitrary request metadata for a single agent run.

Change-Id: I363da000a4bc6545961d17969b9ddc8687445e04

Author: ayushjainn

src/google/adk/cli/api_server.py

@@ -384,6 +384,7 @@ class RunAgentRequest(common.BaseModel):
   function_call_event_id: Optional[str] = None
   # for resume long-running functions
   invocation_id: Optional[str] = None
+  custom_metadata: Optional[dict[str, Any]] = None
 
 
 class CreateSessionRequest(common.BaseModel):
@@ -1415,6 +1416,11 @@ async def run_agent(req: RunAgentRequest) -> list[Event]:
       self.current_app_name_ref.value = req.app_name
       runner = await self.get_runner_async(req.app_name)
       _set_telemetry_context_if_needed(runner)
+      run_config = (
+          RunConfig(custom_metadata=req.custom_metadata)
+          if req.custom_metadata
+          else None
+      )
       try:
         async with Aclosing(
             runner.run_async(
@@ -1423,6 +1429,7 @@ async def run_agent(req: RunAgentRequest) -> list[Event]:
                 new_message=req.new_message,
                 state_delta=req.state_delta,
                 invocation_id=req.invocation_id,
+                run_config=run_config,
             )
         ) as agen:
           events = [event async for event in agen]
@@ -1472,7 +1479,10 @@ async def event_generator():
                 session_id=req.session_id,
                 new_message=req.new_message,
                 state_delta=req.state_delta,
-                run_config=RunConfig(streaming_mode=stream_mode),
+                run_config=RunConfig(
+                    streaming_mode=stream_mode,
+                    custom_metadata=req.custom_metadata,
+                ),
                 invocation_id=req.invocation_id,
             )
         ) as agen:

tests/unittests/cli/test_fast_api.py

@@ -1381,6 +1381,45 @@ async def run_async_capture(
   assert captured_invocation_id["invocation_id"] == payload["invocation_id"]
 
 
+def test_agent_run_passes_custom_metadata(
+    test_app, create_test_session, monkeypatch
+):
+  """Test /run forwards custom_metadata via the run config."""
+  info = create_test_session
+  captured: dict[str, Optional[RunConfig]] = {"run_config": None}
+
+  async def run_async_capture(
+      self,
+      *,
+      user_id: str,
+      session_id: str,
+      invocation_id: Optional[str] = None,
+      new_message: Optional[types.Content] = None,
+      state_delta: Optional[dict[str, Any]] = None,
+      run_config: Optional[RunConfig] = None,
+  ):
+    del self, user_id, session_id, invocation_id, new_message, state_delta
+    captured["run_config"] = run_config
+    yield _event_1()
+
+  monkeypatch.setattr(Runner, "run_async", run_async_capture)
+
+  payload = {
+      "app_name": info["app_name"],
+      "user_id": info["user_id"],
+      "session_id": info["session_id"],
+      "new_message": {"role": "user", "parts": [{"text": "Hello"}]},
+      "streaming": False,
+      "custom_metadata": {"tenant": "acme", "trace": "abc123"},
+  }
+
+  response = test_app.post("/run", json=payload)
+
+  assert response.status_code == 200
+  assert captured["run_config"] is not None
+  assert captured["run_config"].custom_metadata == payload["custom_metadata"]
+
+
 def test_agent_run_sse_splits_artifact_delta(
     test_app, create_test_session, monkeypatch
 ):