feat(agents): forward custom headers to backend A2A agents

In invoke_agent_a2a:
- Extract admin-configured extra_headers from client request by name
- Extract convention-based headers (x-a2a-{agent_id/name}-{header}) from client request
- Merge with static_headers (static wins on conflict)
- Pass merged headers down to asend_message and _handle_stream_message

In asend_message / asend_message_streaming:
- Accept agent_extra_headers kwarg
- Overlay onto LiteLLM internal headers before creating the httpx client

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

litellm/a2a_protocol/main.py

@@ -169,6 +169,7 @@ async def asend_message(
     api_base: Optional[str] = None,
     litellm_params: Optional[Dict[str, Any]] = None,
     agent_id: Optional[str] = None,
+    agent_extra_headers: Optional[Dict[str, str]] = None,
     **kwargs: Any,
 ) -> LiteLLMSendMessageResponse:
     """
@@ -250,9 +251,12 @@ async def asend_message(
                 "Either a2a_client or api_base is required for standard A2A flow"
             )
         trace_id = trace_id or str(uuid.uuid4())
-        extra_headers = {"X-LiteLLM-Trace-Id": trace_id}
+        extra_headers: Dict[str, str] = {"X-LiteLLM-Trace-Id": trace_id}
         if agent_id:
             extra_headers["X-LiteLLM-Agent-Id"] = agent_id
+        # Overlay agent-level headers (agent headers take precedence over LiteLLM internal ones)
+        if agent_extra_headers:
+            extra_headers.update(agent_extra_headers)
         a2a_client = await create_a2a_client(
             base_url=api_base, extra_headers=extra_headers
         )
@@ -426,6 +430,7 @@ async def asend_message_streaming(
     agent_id: Optional[str] = None,
     metadata: Optional[Dict[str, Any]] = None,
     proxy_server_request: Optional[Dict[str, Any]] = None,
+    agent_extra_headers: Optional[Dict[str, str]] = None,
 ) -> AsyncIterator[Any]:
     """
     Async: Send a streaming message to an A2A agent.
@@ -507,7 +512,12 @@ async def asend_message_streaming(
             raise ValueError(
                 "Either a2a_client or api_base is required for standard A2A flow"
             )
-        a2a_client = await create_a2a_client(base_url=api_base)
+        streaming_extra_headers: Optional[Dict[str, str]] = None
+        if agent_extra_headers:
+            streaming_extra_headers = dict(agent_extra_headers)
+        a2a_client = await create_a2a_client(
+            base_url=api_base, extra_headers=streaming_extra_headers
+        )
 
     # Type assertion: a2a_client is guaranteed to be non-None here
     assert a2a_client is not None

litellm/proxy/agent_endpoints/a2a_endpoints.py

@@ -6,13 +6,14 @@ The A2A SDK can point to LiteLLM's URL and invoke agents registered with LiteLLM
 """
 
 import json
-from typing import Any, Optional
+from typing import Any, Dict, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Request, Response
 from fastapi.responses import JSONResponse, StreamingResponse
 
 from litellm._logging import verbose_proxy_logger
 from litellm.proxy._types import UserAPIKeyAuth
+from litellm.proxy.agent_endpoints.utils import merge_agent_headers
 from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
 from litellm.types.utils import all_litellm_params
 
@@ -55,6 +56,7 @@ async def _handle_stream_message(
     metadata: Optional[dict] = None,
     proxy_server_request: Optional[dict] = None,
     *,
+    agent_extra_headers: Optional[Dict[str, str]] = None,
     user_api_key_dict: Optional[UserAPIKeyAuth] = None,
     request_data: Optional[dict] = None,
     proxy_logging_obj: Optional[Any] = None,
@@ -105,6 +107,7 @@ async def _handle_stream_message(
                 agent_id=agent_id,
                 metadata=metadata,
                 proxy_server_request=proxy_server_request,
+                agent_extra_headers=agent_extra_headers,
             )
 
             if (
@@ -385,6 +388,36 @@ async def invoke_agent_a2a(
             version=version,
         )
 
+        # Build merged headers for the backend agent
+        static_headers: Dict[str, str] = dict(agent.static_headers or {})
+
+        raw_headers = dict(request.headers)
+        normalized = {k.lower(): v for k, v in raw_headers.items()}
+
+        dynamic_headers: Dict[str, str] = {}
+
+        # 1. Admin-configured extra_headers: forward named headers from client request
+        if agent.extra_headers:
+            for header_name in agent.extra_headers:
+                val = normalized.get(header_name.lower())
+                if val is not None:
+                    dynamic_headers[header_name] = val
+
+        # 2. Convention-based forwarding: x-a2a-{agent_id_or_name}-{header_name}
+        #    Matches both agent_id (UUID) and agent_name (alias), case-insensitive.
+        for alias in (agent.agent_id.lower(), agent.agent_name.lower()):
+            prefix = f"x-a2a-{alias}-"
+            for key, val in normalized.items():
+                if key.startswith(prefix):
+                    header_name = key[len(prefix) :]
+                    if header_name:
+                        dynamic_headers[header_name] = val
+
+        agent_extra_headers = merge_agent_headers(
+            dynamic_headers=dynamic_headers or None,
+            static_headers=static_headers or None,
+        )
+
         # Route through SDK functions
         if method == "message/send":
             from a2a.types import MessageSendParams, SendMessageRequest
@@ -401,6 +434,7 @@ async def invoke_agent_a2a(
                 metadata=data.get("metadata", {}),
                 proxy_server_request=data.get("proxy_server_request"),
                 litellm_logging_obj=logging_obj,
+                agent_extra_headers=agent_extra_headers,
             )
 
             response = await proxy_logging_obj.post_call_success_hook(
@@ -425,6 +459,7 @@ async def invoke_agent_a2a(
                 agent_id=agent.agent_id,
                 metadata=data.get("metadata", {}),
                 proxy_server_request=data.get("proxy_server_request"),
+                agent_extra_headers=agent_extra_headers,
                 user_api_key_dict=user_api_key_dict,
                 request_data=data,
                 proxy_logging_obj=proxy_logging_obj,