feat(http_options): add dynamic HTTP options support via RunConfig

Enable per-request HTTP configuration (headers, timeout, retry_options) to be
passed via RunConfig and propagated through the request pipeline to models.

Author: Faraaz1994

src/google/adk/agents/run_config.py

@@ -178,7 +178,6 @@ class StreamingMode(Enum):
   For bidirectional streaming, use runner.run_live() instead of run_async().
   """
 
-
 class RunConfig(BaseModel):
   """Configs for runtime behavior of agents.
 
@@ -193,6 +192,9 @@ class RunConfig(BaseModel):
   speech_config: Optional[types.SpeechConfig] = None
   """Speech configuration for the live agent."""
 
+  http_options: Optional[types.HttpOptions] = None
+  """HTTP options for the agent execution (e.g. custom headers)."""
+
   response_modalities: Optional[list[str]] = None
   """The output modalities. If not set, it's default to AUDIO."""
 

src/google/adk/flows/llm_flows/base_llm_flow.py

@@ -520,6 +520,22 @@ async def _preprocess_async(
           f'Expected agent to be an LlmAgent, but got {type(agent)}'
       )
 
+    # Propagate http_options from RunConfig to LlmRequest as defaults.
+    # Request-level settings (from callbacks/processors) take precedence.
+    if (
+        invocation_context.run_config
+        and invocation_context.run_config.http_options
+    ):
+      run_opts = invocation_context.run_config.http_options
+      if not llm_request.config.http_options:
+        # Deep-copy to avoid mutating the user's RunConfig across steps.
+        llm_request.config.http_options = run_opts.model_copy(deep=True)
+      elif run_opts.headers:
+        # Merge headers: request-level headers win (use setdefault).
+        if not llm_request.config.http_options.headers:
+          llm_request.config.http_options.headers = {}
+        for key, value in run_opts.headers.items():
+          llm_request.config.http_options.headers.setdefault(key, value)
     # Runs processors.
     for processor in self.request_processors:
       async with Aclosing(

src/google/adk/flows/llm_flows/basic.py

@@ -17,7 +17,6 @@
 from __future__ import annotations
 
 from typing import AsyncGenerator
-from typing import Generator
 
 from google.genai import types
 from typing_extensions import override
@@ -28,7 +27,6 @@
 from ...utils.output_schema_utils import can_use_output_schema_with_tools
 from ._base_llm_processor import BaseLlmRequestProcessor
 
-
 def _build_basic_request(
     invocation_context: InvocationContext,
     llm_request: LlmRequest,
@@ -45,11 +43,42 @@ def _build_basic_request(
   agent = invocation_context.agent
   model = agent.canonical_model
   llm_request.model = model if isinstance(model, str) else model.model
+
+  # Preserve http_options propagated from RunConfig
+  run_config_http_options = llm_request.config.http_options
+
   llm_request.config = (
       agent.generate_content_config.model_copy(deep=True)
       if agent.generate_content_config
       else types.GenerateContentConfig()
   )
+
+  if run_config_http_options:
+    # Merge RunConfig http_options back, overriding agent config
+    if not llm_request.config.http_options:
+      llm_request.config.http_options = run_config_http_options
+    else:
+      # Merge headers
+      if run_config_http_options.headers:
+        if not llm_request.config.http_options.headers:
+          llm_request.config.http_options.headers = {}
+        llm_request.config.http_options.headers.update(
+            run_config_http_options.headers
+        )
+
+        # Merge other http_options fields if present in RunConfig.
+        # RunConfig values override agent defaults.
+        # Note: base_url, api_version, base_url_resource_scope are intentionally
+        # excluded as they are configuration-time settings, not request-time.
+        for field in [
+            'timeout',
+            'retry_options',
+            'extra_body',
+        ]:
+          val = getattr(run_config_http_options, field, None)
+          if val is not None:
+            setattr(llm_request.config.http_options, field, val)
+
   # Only set output_schema if no tools are specified. as of now, model don't
   # support output_schema and tools together. we have a workaround to support
   # both output_schema and tools at the same time. see
@@ -100,5 +129,4 @@ async def run_async(
     return
     yield  # Generator requires yield statement in function body.
 
-
 request_processor = _BasicLlmRequestProcessor()