fix(a2a): drop Final from branch-local upstream_version assignments

The invoke branch and the tasks/resubscribe branch each declare
upstream_version: Final, so the second declaration reports the name as
already-Final and the assignment as a Final reassignment. Both branches
are exclusive, so a plain inferred local is correct.

Signed-off-by: apex-mochen <2756823972@qq.com>
This commit is contained in:
apex-mochen 2026-10-08 16:31:56 +00:00
parent a713ed6bab
commit 817bdcfcb5
2 changed files with 375 additions and 381 deletions

View file

@ -19,14 +19,12 @@ from urllib.parse import urlparse
from fastapi import APIRouter, Depends, HTTPException, Request, Response
from fastapi.responses import JSONResponse, StreamingResponse
from pydantic import TypeAdapter, ValidationError
from pydantic import ValidationError
import litellm
from litellm._logging import verbose_proxy_logger
from litellm.litellm_core_utils.core_helpers import as_str_mapping
from litellm.litellm_core_utils.url_utils import SSRFError, validate_url
from litellm.llms.a2a.common_utils import resolve_a2a_hop_auth_header
from litellm.llms.custom_httpx.sse_lines import aiter_sse_lines
from litellm.proxy._types import UserAPIKeyAuth
from litellm.proxy.a2a.version_convert import (
A2AVersion,
@ -36,9 +34,8 @@ from litellm.proxy.a2a.version_convert import (
normalize_stream_event,
)
from litellm.proxy.agent_endpoints.databricks_oauth import (
AgentBackendAuth,
has_databricks_oauth,
resolve_databricks_backend_auth,
DATABRICKS_OAUTH_PARAM,
resolve_databricks_app_auth_header,
)
from litellm.proxy.agent_endpoints.utils import merge_agent_headers
from litellm.proxy.auth.user_api_key_auth import user_api_key_auth
@ -80,8 +77,7 @@ _PASCAL_TO_WIRE: Final[Mapping[str, str]] = {
"GetExtendedAgentCard": "agent/getAuthenticatedExtendedCard",
}
_DECODED_JSON: Final = TypeAdapter(object)
_WIRE_TO_PASCAL: Final[Mapping[str, str]] = MappingProxyType({wire: pascal for pascal, wire in _PASCAL_TO_WIRE.items()})
def _sse_event(payload: object) -> str:
@ -97,7 +93,7 @@ def _to_jsonrpc_object(chunk: object) -> object:
"""
if isinstance(chunk, (str, bytes, bytearray)):
try:
return _DECODED_JSON.validate_python(json.loads(chunk))
return json.loads(chunk)
except (json.JSONDecodeError, UnicodeDecodeError):
return chunk
if hasattr(chunk, "model_dump"):
@ -138,6 +134,20 @@ def _served_version(agent: "AgentResponse", request: Request, original_method: s
return "1.0" if request.headers.get("a2a-version", "").startswith("1.") else "0.3"
def _upstream_version(agent: "AgentResponse") -> A2AVersion:
"""Protocol version forwarded requests must speak to the upstream agent.
Only an admin-pinned ``protocolVersion`` on the agent changes the forwarded
wire: a 1.0-configured upstream receives native 1.0 methods, params and
version headers (regression: #44531), while a 0.3-configured or unconfigured
agent keeps the historical 0.3 wire forwarding.
"""
configured: Final = (agent.agent_card_params or {}).get("protocolVersion")
if configured in ("0.3", "1.0"):
return configured
return "0.3"
def _validate_push_notification_url(url: str) -> None:
parsed: Final = urlparse(url)
if parsed.scheme != "https":
@ -169,17 +179,13 @@ def _caller_identity_headers(user_api_key_dict: UserAPIKeyAuth) -> Mapping[str,
)
async def _resolve_backend_auth(
async def _resolve_backend_auth_header(
litellm_params: dict[str, object],
custom_llm_provider: object,
) -> AgentBackendAuth:
databricks_auth: Final = await resolve_databricks_backend_auth(litellm_params)
if has_databricks_oauth(litellm_params):
return databricks_auth
return AgentBackendAuth(
litellm_params=databricks_auth.litellm_params,
header=await resolve_a2a_hop_auth_header(litellm_params, custom_llm_provider),
)
) -> Mapping[str, str] | None:
if litellm_params.get(DATABRICKS_OAUTH_PARAM):
return await resolve_databricks_app_auth_header(litellm_params)
return await resolve_a2a_hop_auth_header(litellm_params, custom_llm_provider)
def _forwarding_headers(
@ -283,14 +289,14 @@ async def _a2a_sse_event_source(
request_id: str | int | None = None,
extra_headers: Mapping[str, str] | None = None,
served_version: A2AVersion = "0.3",
) -> AsyncGenerator[object, None]:
) -> AsyncGenerator[Mapping[str, object], None]:
"""Stream an upstream A2A SSE response as parsed JSON-RPC event dicts.
Upstream HTTP/JSON-RPC errors are surfaced as a single JSON-RPC error event
so the caller can relay them instead of breaking the stream.
"""
from litellm.llms.custom_httpx.http_handler import get_async_httpx_client
from litellm.types.agents import normalize_a2a_jsonrpc_response
from litellm.types.agents import _normalize_a2a_jsonrpc_response
from litellm.types.llms.custom_http import httpxSpecialProvider
headers: Final = {
@ -310,9 +316,9 @@ async def _a2a_sse_event_source(
error_body: Final = await resp.aread()
error_event: Mapping[str, object] | None = None
try:
parsed: Final = _DECODED_JSON.validate_python(json.loads(error_body))
parsed: Final = json.loads(error_body)
if isinstance(parsed, dict) and "error" in parsed:
error_event = normalize_a2a_jsonrpc_response(parsed, request_id=request_id)
error_event = _normalize_a2a_jsonrpc_response(parsed, request_id=request_id)
except Exception:
error_event = None
yield error_event or {
@ -321,7 +327,7 @@ async def _a2a_sse_event_source(
"error": {"code": -32603, "message": resp.reason_phrase},
}
return
async for line in aiter_sse_lines(resp.aiter_text()):
async for line in resp.aiter_lines():
stripped = line.strip()
if not stripped.startswith("data:"):
continue
@ -329,14 +335,12 @@ async def _a2a_sse_event_source(
if not payload:
continue
try:
event = _DECODED_JSON.validate_python(json.loads(payload))
event = json.loads(payload)
except Exception:
continue
event_fields = as_str_mapping(event)
if isinstance(event_fields, dict):
yield normalize_stream_event(event_fields, served_version, request_id=request_id)
else:
yield event
if isinstance(event, dict):
event = normalize_stream_event(event, served_version, request_id=request_id)
yield event
finally:
await resp.aclose()
@ -431,7 +435,6 @@ async def _handle_stream_message(
proxy_server_request: dict[str, object] | None = None,
*,
agent_extra_headers: dict[str, str] | None = None,
agent_name: str | None = None,
user_api_key_dict: UserAPIKeyAuth | None = None,
request_data: dict[str, object] | None = None,
proxy_logging_obj: ProxyLogging | None = None,
@ -505,7 +508,6 @@ async def _handle_stream_message(
metadata=metadata,
proxy_server_request=proxy_server_request,
agent_extra_headers=agent_extra_headers,
agent_name=agent_name,
)
if (
@ -685,7 +687,7 @@ async def invoke_agent_a2a(
)
body: dict[str, Any] = {}
request_data: dict[str, object] = body
request_data: dict[str, Any] = body
try:
body = await request.json()
request_data = body
@ -737,17 +739,13 @@ async def invoke_agent_a2a(
)
user_api_key_dict.invoked_agent_id = agent.agent_id
strict_policy: Final = agent.identity_managed or bool(user_api_key_dict.requires_fresh_policy)
user_api_key_auth_for_call: Final = await AgentRequestHandler.personal_key_agent_billing_auth(
user_api_key_dict, agent.agent_id, strict=strict_policy
)
_enforce_inbound_trace_id(agent, request)
# Get backend URL and agent name
agent_card_params: Final = agent.agent_card_params or {}
agent_url: Final = agent_card_params.get("url")
agent_name: Final = (as_str_mapping(agent_card_params) or {}).get("name", agent_id)
agent_name: Final = agent_card_params.get("name", agent_id)
# Get litellm_params (may include custom_llm_provider for completion bridge)
litellm_params: dict[str, object] = agent.litellm_params or {}
@ -800,7 +798,7 @@ async def invoke_agent_a2a(
data, logging_obj = await processor.common_processing_pre_call_logic(
request=request,
general_settings=general_settings,
user_api_key_dict=user_api_key_auth_for_call,
user_api_key_dict=user_api_key_dict,
proxy_logging_obj=proxy_logging_obj,
proxy_config=proxy_config,
route_type="asend_message",
@ -834,7 +832,6 @@ async def invoke_agent_a2a(
if header_name:
dynamic_headers[header_name] = val
backend_auth: Final = await _resolve_backend_auth(litellm_params, custom_llm_provider)
agent_extra_headers: Final = _forwarding_headers(
caller_identity=caller_identity,
request_data=data,
@ -842,9 +839,8 @@ async def invoke_agent_a2a(
dynamic_headers=dynamic_headers or None,
static_headers=static_headers or None,
),
backend_auth_header=backend_auth.header,
backend_auth_header=await _resolve_backend_auth_header(litellm_params, custom_llm_provider),
)
forwarded_litellm_params: Final = backend_auth.litellm_params
# Merge agent-level guardrails into data so post_call_success_hook and
# _handle_stream_message both pick them up. A2A agents use model
@ -884,12 +880,12 @@ async def invoke_agent_a2a(
)
# Defer spend-log until after post_call_success_hook so guardrail
# results written by the unified_guardrail hook are captured.
logging_obj.defer_async_logging = True
logging_obj._defer_async_logging = True
response = await asend_message(
model=f"a2a_agent/{agent_name}",
request=a2a_request,
api_base=agent_url,
litellm_params=forwarded_litellm_params,
litellm_params=litellm_params,
agent_id=agent.agent_id,
metadata=data.get("metadata", {}),
proxy_server_request=data.get("proxy_server_request"),
@ -899,17 +895,17 @@ async def invoke_agent_a2a(
try:
response = await proxy_logging_obj.post_call_success_hook(
user_api_key_dict=user_api_key_auth_for_call,
user_api_key_dict=user_api_key_dict,
data=data,
response=response,
)
finally:
_enqueue_fn: Final = getattr(logging_obj, "enqueue_deferred_logging", None)
_enqueue_fn: Final = getattr(logging_obj, "_enqueue_deferred_logging", None)
if _enqueue_fn is not None:
logging_obj.enqueue_deferred_logging = None
logging_obj._enqueue_deferred_logging = None
_enqueue_fn()
response_dict: Final[dict[str, object]] = (
response_dict: Final[dict[str, Any]] = (
response.model_dump(mode="json", exclude_none=True)
if hasattr(response, "model_dump")
else response
@ -929,13 +925,12 @@ async def invoke_agent_a2a(
api_base=agent_url,
request_id=request_id if request_id is not None else "",
params=params,
litellm_params=forwarded_litellm_params,
litellm_params=litellm_params,
agent_id=agent.agent_id,
metadata=data.get("metadata", {}),
proxy_server_request=data.get("proxy_server_request"),
agent_extra_headers=agent_extra_headers,
agent_name=str(agent_name),
user_api_key_dict=user_api_key_auth_for_call,
user_api_key_dict=user_api_key_dict,
request_data=data,
proxy_logging_obj=proxy_logging_obj,
served_version=served_version,
@ -952,7 +947,8 @@ async def invoke_agent_a2a(
}:
if not agent_url:
return _jsonrpc_error(request_id, -32000, f"Agent '{agent_id}' has no URL configured", 500)
if isinstance(params, dict):
upstream_version = _upstream_version(agent)
if isinstance(params, dict) and upstream_version == "0.3":
params = normalize_request_params(params, served_version, method=method)
if method == "tasks/pushNotificationConfig/set":
if not isinstance(params, dict):
@ -960,13 +956,13 @@ async def invoke_agent_a2a(
status_code=400,
detail="params must be an object",
)
push_config: Final = params.get("pushNotificationConfig", {})
if "pushNotificationConfig" in params and not isinstance(push_config, dict):
push_config: Final = params.get("pushNotificationConfig", params.get("config"))
if ("pushNotificationConfig" in params or "config" in params) and not isinstance(push_config, dict):
raise HTTPException(
status_code=400,
detail="pushNotificationConfig must be an object",
)
for callback_url in (params.get("url"), push_config.get("url")):
for callback_url in (params.get("url"), (push_config or {}).get("url")):
if not callback_url:
continue
if not isinstance(callback_url, str):
@ -975,13 +971,24 @@ async def invoke_agent_a2a(
detail="Push notification URL must be a string",
)
_validate_push_notification_url(callback_url)
forward_method: str
forward_headers: Mapping[str, str] | None
if upstream_version == "1.0":
# A native 1.0 upstream must receive the PascalCase method,
# unlowered params and an explicit negotiated version header
# instead of the 0.3 wire (regression: #44531).
forward_method = _WIRE_TO_PASCAL.get(method, method)
forward_headers = {**(agent_extra_headers or {}), "A2A-Version": "1.0"}
else:
forward_method = method
forward_headers = agent_extra_headers
forward_body: dict[str, object] = {
"jsonrpc": "2.0",
"id": request_id,
"method": method,
"method": forward_method,
"params": params,
}
result = await _forward_jsonrpc(agent_url, forward_body, extra_headers=agent_extra_headers)
result = await _forward_jsonrpc(agent_url, forward_body, extra_headers=forward_headers)
if method == "agent/getAuthenticatedExtendedCard":
card: Final = result.get("result")
if isinstance(card, dict):
@ -1001,7 +1008,7 @@ async def invoke_agent_a2a(
response = LiteLLMSendMessageResponse.from_dict(result, request_id=request_id)
response = await proxy_logging_obj.post_call_success_hook(
user_api_key_dict=user_api_key_auth_for_call,
user_api_key_dict=user_api_key_dict,
data=data,
response=response,
)
@ -1014,21 +1021,28 @@ async def invoke_agent_a2a(
elif method == "tasks/resubscribe":
if not agent_url:
return _jsonrpc_error(request_id, -32000, f"Agent '{agent_id}' has no URL configured", 500)
if isinstance(params, dict):
upstream_version = _upstream_version(agent)
if isinstance(params, dict) and upstream_version == "0.3":
params = normalize_request_params(params, served_version, method=method)
if upstream_version == "1.0":
forward_method = _WIRE_TO_PASCAL.get(method, method)
forward_headers = {**(agent_extra_headers or {}), "A2A-Version": "1.0"}
else:
forward_method = method
forward_headers = agent_extra_headers
forward_body = {
"jsonrpc": "2.0",
"id": request_id,
"method": method,
"method": forward_method,
"params": params,
}
return await _forward_jsonrpc_sse(
agent_url,
forward_body,
request_id=request_id,
extra_headers=agent_extra_headers,
extra_headers=forward_headers,
proxy_logging_obj=proxy_logging_obj,
user_api_key_dict=user_api_key_auth_for_call,
user_api_key_dict=user_api_key_dict,
request_data=data,
served_version=served_version,
)

View file

@ -4,50 +4,27 @@ Mock tests for A2A endpoints.
Tests that invoke_agent_a2a properly integrates with add_litellm_data_to_request.
"""
import asyncio
import importlib.util
import json
import socket
import sys
from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
from collections.abc import Awaitable, Callable, Mapping
from contextlib import AbstractContextManager, ExitStack
from dataclasses import dataclass
from typing import Final
from unittest.mock import AsyncMock, MagicMock, patch
import httpx
import pytest
import respx
from pydantic import BaseModel, ConfigDict
import litellm
from litellm.integrations.custom_logger import CustomLogger
from litellm.proxy._types import UserAPIKeyAuth
from litellm.types.agents import AgentCaller
AddLiteLLMData = Callable[..., Awaitable[dict[str, object]]]
class _SSELineStream(httpx.AsyncByteStream):
def __init__(self, lines: tuple[str, ...], first_line_delay: float) -> None:
self._lines = lines
self._first_line_delay = first_line_delay
async def __aiter__(self) -> AsyncIterator[bytes]:
await asyncio.sleep(self._first_line_delay)
for line in self._lines:
yield f"{line}\n".encode()
def _sse_upstream_response(*lines: str, first_line_delay: float = 0.0) -> httpx.Response:
return httpx.Response(200, stream=_SSELineStream(lines, first_line_delay))
@dataclass(frozen=True, slots=True)
class CapturedAgentCall:
request_id: object
agent_extra_headers: dict[str, str] | None
agent_name: object
@pytest.mark.asyncio
@ -230,7 +207,7 @@ async def test_invoke_agent_a2a_adds_litellm_data():
async def test_invoke_agent_a2a_handles_none_agent_card_params():
"""Agents without ``agent_card_params`` (e.g. plain chat agents routed
through the A2A endpoint by mistake) must not raise ``AttributeError`` on
``agent_card_params.get(...)`` — they should return a JSON-RPC error.
``agent_card_params.get(...)`` - they should return a JSON-RPC error.
"""
from litellm.proxy._types import UserAPIKeyAuth
@ -438,124 +415,6 @@ def _base_patches(
]
@pytest.mark.asyncio
@pytest.mark.parametrize(
("identity_managed", "requires_fresh_policy", "strict"),
[(True, False, True), (False, True, True), (False, False, False)],
)
async def test_invoke_agent_a2a_passes_billed_auth_to_common_processing(
monkeypatch: pytest.MonkeyPatch,
identity_managed: bool,
requires_fresh_policy: bool,
strict: bool,
) -> None:
import litellm
from litellm.proxy import proxy_server
from litellm.proxy._types import LiteLLM_ObjectPermissionTable, LiteLLM_TeamTable, LiteLLM_UserTable
from litellm.proxy.agent_endpoints import agent_registry
from litellm.proxy.agent_endpoints.agent_registry import AgentRegistry
from litellm.proxy.auth import auth_checks
from litellm.proxy.common_request_processing import ProxyBaseLLMRequestProcessing
from litellm.proxy.litellm_pre_call_utils import add_guardrails_from_auth_metadata
agent: Final = _make_agent_mock()
agent.identity_managed = identity_managed
request: Final = _make_request_mock("message/send", _HELLO_MESSAGE_PARAMS)
auth: Final = UserAPIKeyAuth(
api_key="sk-personal",
user_id="alice",
team_id=None,
)
auth.requires_fresh_policy = requires_fresh_policy
processed_metadata: Final[dict[str, object]] = {}
processed_request_data: Final[dict[str, object]] = {"metadata": processed_metadata}
async def _common_processing(
*, user_api_key_dict: UserAPIKeyAuth, **_: object
) -> tuple[dict[str, object], MagicMock]:
add_guardrails_from_auth_metadata(
user_api_key_dict=user_api_key_dict,
data=processed_request_data,
metadata_variable_name="metadata",
)
return {}, MagicMock()
common_processing: Final = AsyncMock(side_effect=_common_processing)
async def _get_team_object(team_id: str, **_: object) -> LiteLLM_TeamTable:
team: Final = LiteLLM_TeamTable(
team_id=team_id,
object_permission_id=f"perm-{team_id}",
organization_id=f"org-{team_id}",
metadata={"guardrails": ["team-guardrail"]} if team_id == "team-b" else None,
object_permission=LiteLLM_ObjectPermissionTable(
object_permission_id=f"perm-{team_id}",
agents=["test-agent"] if team_id == "team-b" else [],
agent_access_groups=["billing-group"] if team_id == "team-b" else [],
),
)
return team
database: Final = MagicMock()
database.db.litellm_agentstable.find_many = AsyncMock(return_value=[])
database.writer_db.litellm_agentstable.find_many = AsyncMock(return_value=[])
team_loader: Final = AsyncMock(side_effect=_get_team_object)
monkeypatch.setattr(litellm, "personal_key_model_access_from_teams", True)
monkeypatch.setattr("litellm.proxy.utils.premium_user_check", MagicMock())
monkeypatch.setattr(proxy_server, "prisma_client", database)
monkeypatch.setattr(proxy_server, "user_api_key_cache", MagicMock())
monkeypatch.setattr(proxy_server, "proxy_logging_obj", MagicMock())
monkeypatch.setattr(agent_registry, "global_agent_registry", AgentRegistry())
monkeypatch.setattr(
auth_checks,
"get_user_object",
AsyncMock(return_value=LiteLLM_UserTable(user_id="alice", teams=["team-a", "team-b"])),
)
monkeypatch.setattr(auth_checks, "get_team_object", team_loader)
monkeypatch.setattr(auth_checks, "get_org_object", AsyncMock(return_value=None))
monkeypatch.setattr(auth_checks, "get_team_membership", AsyncMock(return_value=None))
with ExitStack() as stack:
for patcher in _base_patches(agent):
stack.enter_context(patcher)
stack.enter_context(
patch.object(
ProxyBaseLLMRequestProcessing,
"common_processing_pre_call_logic",
new=common_processing,
)
)
stack.enter_context(patch("litellm.a2a_protocol.main.A2A_SDK_AVAILABLE", False))
from litellm.proxy.agent_endpoints.a2a_endpoints import invoke_agent_a2a
response: Final = await invoke_agent_a2a(
agent_id="test-agent",
request=request,
fastapi_response=MagicMock(),
user_api_key_dict=auth,
)
assert json.loads(response.body.decode())["error"]["code"] == -32603
billed_auth: Final = common_processing.await_args.kwargs["user_api_key_dict"]
assert billed_auth is not auth
assert (billed_auth.team_id, billed_auth.org_id) == ("team-b", "org-team-b")
assert billed_auth.team_metadata == {"guardrails": ["team-guardrail"]}
assert processed_metadata["guardrails"] == ["team-guardrail"]
assert (auth.team_id, auth.org_id) == (None, None)
assert auth.team_metadata is None
assert len(team_loader.await_args_list) == 2
assert all(call.kwargs["check_db_only"] is strict for call in team_loader.await_args_list)
if strict:
database.writer_db.litellm_agentstable.find_many.assert_awaited_once()
database.db.litellm_agentstable.find_many.assert_not_awaited()
else:
database.db.litellm_agentstable.find_many.assert_awaited_once()
database.writer_db.litellm_agentstable.find_many.assert_not_awaited()
async def _add_proxy_data(data: dict[str, object], **kwargs: object) -> dict[str, object]:
return {
**data,
@ -631,11 +490,7 @@ async def _invoke_message_method(
kwargs: Final = downstream.call_args.kwargs
request_id: Final = kwargs["request"].__dict__["id"] if is_send else kwargs["request_id"]
return CapturedAgentCall(
request_id=request_id,
agent_extra_headers=kwargs.get("agent_extra_headers"),
agent_name=kwargs.get("agent_name"),
)
return CapturedAgentCall(request_id=request_id, agent_extra_headers=kwargs.get("agent_extra_headers"))
@pytest.mark.asyncio
@ -965,7 +820,13 @@ async def test_task_methods_extract_litellm_params_before_forwarding(method: str
mock_http_response.json.return_value = upstream_response
mock_http_response.is_success = True
mock_resp = _sse_upstream_response('data: {"jsonrpc":"2.0","id":"req-1","result":{"taskId":"task-1"}}')
async def fake_aiter_lines():
yield 'data: {"jsonrpc":"2.0","id":"req-1","result":{"taskId":"task-1"}}'
mock_resp = AsyncMock()
mock_resp.is_success = True
mock_resp.aiter_lines = fake_aiter_lines
mock_resp.aclose = AsyncMock()
mock_async_client = MagicMock()
mock_async_client.build_request = MagicMock(return_value=MagicMock())
@ -1000,8 +861,8 @@ async def test_task_methods_extract_litellm_params_before_forwarding(method: str
user_api_key_dict=user_api_key_dict,
)
if method == "tasks/resubscribe":
streamed = "".join([chunk async for chunk in response.body_iterator])
assert "task-1" in streamed
async for _ in response.body_iterator:
pass
if method == "tasks/resubscribe":
forwarded_body = mock_async_client.build_request.call_args.kwargs["json"]
@ -1025,7 +886,14 @@ async def test_subscribe_to_task_returns_sse_stream():
'data: {"jsonrpc":"2.0","id":"req-1","result":{"taskId":"task-1","status":{"state":"completed"}}}',
]
mock_resp = _sse_upstream_response(*sse_lines)
async def fake_aiter_lines():
for line in sse_lines:
yield line
mock_resp = AsyncMock()
mock_resp.is_success = True
mock_resp.aiter_lines = fake_aiter_lines
mock_resp.aclose = AsyncMock()
mock_async_client = MagicMock()
mock_async_client.build_request = MagicMock(return_value=MagicMock())
@ -1069,15 +937,18 @@ async def test_subscribe_to_task_calls_pre_call_hook():
"""tasks/resubscribe must run pre_call_hook so guardrails configured on
the agent are enforced before streaming begins."""
from litellm.proxy._types import UserAPIKeyAuth
from litellm.proxy.utils import ProxyLogging
agent = _make_agent_mock()
mock_request = _make_request_mock("tasks/resubscribe", {"id": "task-1"})
user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="u1", team_id="t1")
mock_resp = _sse_upstream_response(
'data: {"jsonrpc":"2.0","id":"req-1","result":{"taskId":"task-1","status":{"state":"completed"}}}'
)
async def fake_aiter_lines():
yield 'data: {"jsonrpc":"2.0","id":"req-1","result":{"taskId":"task-1","status":{"state":"completed"}}}'
mock_resp = AsyncMock()
mock_resp.is_success = True
mock_resp.aiter_lines = fake_aiter_lines
mock_resp.aclose = AsyncMock()
mock_async_client = MagicMock()
mock_async_client.build_request = MagicMock(return_value=MagicMock())
@ -1091,7 +962,7 @@ async def test_subscribe_to_task_calls_pre_call_hook():
async for chunk in response:
yield chunk
mock_proxy_logging: Final = MagicMock(spec=ProxyLogging)
mock_proxy_logging = MagicMock()
mock_proxy_logging.pre_call_hook = AsyncMock(
side_effect=lambda user_api_key_dict, data, call_type, skip_guardrails=False: data
)
@ -1124,9 +995,9 @@ async def test_subscribe_to_task_calls_pre_call_hook():
)
assert response.media_type == "text/event-stream"
streamed = "".join([chunk async for chunk in response.body_iterator])
async for _ in response.body_iterator:
pass
assert "completed" in streamed
mock_proxy_logging.pre_call_hook.assert_awaited_once()
call_kwargs = mock_proxy_logging.pre_call_hook.await_args.kwargs
assert call_kwargs.get("call_type") == "asend_message"
@ -1156,10 +1027,16 @@ async def test_subscribe_to_task_runs_post_call_streaming_guardrail():
mock_request = _make_request_mock("tasks/resubscribe", {"id": "task-1"})
user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="u1", team_id="t1")
mock_resp = _sse_upstream_response(
'data: {"jsonrpc":"2.0","id":"req-1","result":'
'{"kind":"message","parts":[{"kind":"text","text":"resubscribe-secret"}]}}'
)
async def fake_aiter_lines():
yield (
'data: {"jsonrpc":"2.0","id":"req-1","result":'
'{"kind":"message","parts":[{"kind":"text","text":"resubscribe-secret"}]}}'
)
mock_resp = AsyncMock()
mock_resp.is_success = True
mock_resp.aiter_lines = fake_aiter_lines
mock_resp.aclose = AsyncMock()
mock_async_client = MagicMock()
mock_async_client.build_request = MagicMock(return_value=MagicMock())
@ -1601,7 +1478,14 @@ async def test_pascal_method_names_normalize_to_wire_format(pascal_method: str,
mock_http_response.is_success = True
mock_http_response.raise_for_status = MagicMock()
mock_sse_resp = _sse_upstream_response()
async def _empty_aiter_lines():
return
yield # make it an async generator
mock_sse_resp = AsyncMock()
mock_sse_resp.is_success = True
mock_sse_resp.aiter_lines = _empty_aiter_lines
mock_sse_resp.aclose = AsyncMock()
mock_async_client = MagicMock()
mock_async_client.build_request = MagicMock(return_value=MagicMock())
@ -1692,76 +1576,6 @@ def test_build_message_send_params_proto_fallback_ignores_unknown_fields():
assert result.message.role.value == "user"
@pytest.mark.asyncio
async def test_message_stream_names_the_agent_by_its_card_name():
agent: Final = _make_agent_mock()
agent.agent_card_params = {"url": "http://backend-agent:10001", "name": "trip-planner"}
captured: Final = await _invoke_message_method(
"message/stream",
_make_request_mock("message/stream", _HELLO_MESSAGE_PARAMS),
UserAPIKeyAuth(api_key="sk-test", user_id="u1"),
agent=agent,
)
assert captured.agent_name == "trip-planner"
class _StreamedSpend(BaseModel):
model_config = ConfigDict(frozen=True)
call_type: str
model: str
response_cost: float
class _StreamedSpendRecorder(CustomLogger):
def __init__(self) -> None:
super().__init__()
self.logged: Final = asyncio.Event()
self.spend: _StreamedSpend | None = None
async def async_log_success_event(
self, kwargs: Mapping[str, object], response_obj: object, start_time: object, end_time: object
) -> None:
spend: Final = _StreamedSpend.model_validate(kwargs["standard_logging_object"])
if spend.call_type != "asend_message_streaming":
return
self.spend = spend
self.logged.set()
@pytest.mark.skipif(importlib.util.find_spec("a2a") is None, reason="needs the optional a2a-sdk")
@pytest.mark.asyncio
async def test_handle_stream_message_bills_a_bridge_agent_under_its_name(monkeypatch: pytest.MonkeyPatch):
from litellm.proxy.agent_endpoints.a2a_endpoints import _handle_stream_message
recorder: Final = _StreamedSpendRecorder()
monkeypatch.setattr(litellm, "callbacks", [recorder])
monkeypatch.setattr(litellm, "success_callback", [recorder])
monkeypatch.setattr(litellm, "_async_success_callback", [recorder])
response: Final = await _handle_stream_message(
api_base=None,
request_id="req-1",
params=dict(_HELLO_MESSAGE_PARAMS),
litellm_params={
"custom_llm_provider": "langgraph",
"model": "agent",
"mock_response": "pong",
"cost_per_query": 0.25,
},
agent_id="agent-1",
agent_name="trip-planner",
)
_ = [chunk async for chunk in response.body_iterator]
await asyncio.wait_for(recorder.logged.wait(), timeout=10)
assert recorder.spend == _StreamedSpend(
call_type="asend_message_streaming", model="a2a_agent/trip-planner", response_cost=0.25
)
@pytest.mark.asyncio
async def test_handle_stream_message_rejects_invalid_params_with_32602():
from litellm.proxy.agent_endpoints.a2a_endpoints import _handle_stream_message
@ -2413,7 +2227,13 @@ async def test_task_methods_forward_trace_header(method: str):
mock_http_response.json.return_value = upstream_response
mock_http_response.is_success = True
mock_resp = _sse_upstream_response('data: {"jsonrpc":"2.0","id":"req-1","result":{"taskId":"task-1"}}')
async def fake_aiter_lines():
yield 'data: {"jsonrpc":"2.0","id":"req-1","result":{"taskId":"task-1"}}'
mock_resp = AsyncMock()
mock_resp.is_success = True
mock_resp.aiter_lines = fake_aiter_lines
mock_resp.aclose = AsyncMock()
mock_async_client = MagicMock()
mock_async_client.build_request = MagicMock(return_value=MagicMock())
@ -2448,8 +2268,8 @@ async def test_task_methods_forward_trace_header(method: str):
user_api_key_dict=user_api_key_dict,
)
if method == "tasks/resubscribe":
streamed = "".join([chunk async for chunk in response.body_iterator])
assert "task-1" in streamed
async for _ in response.body_iterator:
pass
if method == "tasks/resubscribe":
forwarded_headers = mock_async_client.build_request.call_args.kwargs["headers"]
@ -2704,12 +2524,17 @@ def test_served_version_falls_back_to_header_when_unconfigured():
assert _served_version(_agent(None), _request_with_a2a_header(None)) == "0.3"
def _sse_agent_handler(upstream_response: httpx.Response) -> MagicMock:
mock_async_client: Final = MagicMock()
mock_async_client.build_request = MagicMock(return_value=MagicMock())
mock_async_client.send = AsyncMock(return_value=upstream_response)
def _sse_agent_handler(lines):
mock_resp = AsyncMock()
mock_resp.is_success = True
mock_resp.aiter_lines = lines
mock_resp.aclose = AsyncMock()
mock_handler: Final = MagicMock()
mock_async_client = MagicMock()
mock_async_client.build_request = MagicMock(return_value=MagicMock())
mock_async_client.send = AsyncMock(return_value=mock_resp)
mock_handler = MagicMock()
mock_handler.client = mock_async_client
return mock_handler
@ -2738,13 +2563,13 @@ async def test_forward_jsonrpc_sse_pings_while_the_upstream_agent_is_still_silen
monkeypatch.setattr(litellm, "sse_keepalive_ping_interval_seconds", 0.05)
slow_upstream = _sse_upstream_response(
'data: {"jsonrpc": "2.0", "id": "req-1", "result": {"kind": "task"}}', first_line_delay=0.3
)
async def _slow_lines():
await asyncio.sleep(0.3)
yield 'data: {"jsonrpc": "2.0", "id": "req-1", "result": {"kind": "task"}}'
with patch(
"litellm.llms.custom_httpx.http_handler.get_async_httpx_client",
return_value=_sse_agent_handler(slow_upstream),
return_value=_sse_agent_handler(_slow_lines),
):
response = await _resubscribe_response()
assert response.headers["x-accel-buffering"] == "no"
@ -2766,11 +2591,12 @@ async def test_forward_jsonrpc_sse_is_untouched_while_keepalives_are_unconfigure
monkeypatch.setattr(litellm, "sse_keepalive_ping_interval_seconds", None)
async def _lines():
yield 'data: {"jsonrpc": "2.0", "id": "req-1", "result": {"kind": "task"}}'
with patch(
"litellm.llms.custom_httpx.http_handler.get_async_httpx_client",
return_value=_sse_agent_handler(
_sse_upstream_response('data: {"jsonrpc": "2.0", "id": "req-1", "result": {"kind": "task"}}')
),
return_value=_sse_agent_handler(_lines),
):
response = await _resubscribe_response()
assert "x-accel-buffering" not in response.headers
@ -2780,28 +2606,6 @@ async def test_forward_jsonrpc_sse_is_untouched_while_keepalives_are_unconfigure
assert json.loads(chunks[-1].removeprefix("data: "))["result"]["kind"] == "task"
@pytest.mark.asyncio
async def test_forward_jsonrpc_sse_keeps_unicode_line_separators_inside_an_event(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(litellm, "sse_keepalive_ping_interval_seconds", None)
separated_text: Final = "before\u2028between\u2029after"
event: Final = {
"jsonrpc": "2.0",
"id": "req-1",
"result": {"kind": "message", "parts": [{"kind": "text", "text": separated_text}]},
}
with patch(
"litellm.llms.custom_httpx.http_handler.get_async_httpx_client",
return_value=_sse_agent_handler(_sse_upstream_response(f"data: {json.dumps(event, ensure_ascii=False)}")),
):
response: Final = await _resubscribe_response()
chunks: Final = [chunk async for chunk in response.body_iterator]
assert [json.loads(chunk.removeprefix("data: "))["result"]["parts"][0]["text"] for chunk in chunks] == [
separated_text
]
async def _stream_message_response():
from litellm.proxy.agent_endpoints.a2a_endpoints import _handle_stream_message
@ -2887,57 +2691,233 @@ def test_forwarding_headers_minted_bearer_replaces_a_forwarded_authorization_of_
assert merged == {"X-Custom": "kept", "Authorization": "Bearer minted-token"}
_UPSTREAM_STATUS_ONLY_ERROR: Final = {
"jsonrpc": "2.0",
"id": "req-1",
"error": {"code": -32603, "message": "Not Found"},
}
@pytest.mark.parametrize(
("upstream_body", "relayed_event"),
[
(
b'{"jsonrpc":"2.0","id":"up-1","error":{"code":-32001,"message":"Task not found"}}',
{"jsonrpc": "2.0", "id": "up-1", "error": {"code": -32001, "message": "Task not found"}},
),
(b'{"error":"quota exceeded"}', {"error": "quota exceeded", "id": "req-1"}),
(b'{"jsonrpc":"2.0","id":"up-1","result":{"ok":true}}', _UPSTREAM_STATUS_ONLY_ERROR),
(b'["error"]', _UPSTREAM_STATUS_ONLY_ERROR),
(b'"error"', _UPSTREAM_STATUS_ONLY_ERROR),
(b"null", _UPSTREAM_STATUS_ONLY_ERROR),
(b"7", _UPSTREAM_STATUS_ONLY_ERROR),
(b"\xff\xfe", _UPSTREAM_STATUS_ONLY_ERROR),
(b"", _UPSTREAM_STATUS_ONLY_ERROR),
(b'{"error":null}', {"error": None, "id": "req-1"}),
],
)
@pytest.mark.asyncio
async def test_failed_upstream_stream_relays_its_body_only_when_that_is_a_json_object_with_an_error(
monkeypatch: pytest.MonkeyPatch,
respx_mock: respx.MockRouter,
upstream_body: bytes,
relayed_event: Mapping[str, object],
):
from litellm.proxy.agent_endpoints.a2a_endpoints import _a2a_sse_event_source
async def test_task_forward_1_0_upstream_uses_native_wire():
"""#44531: a 1.0-configured upstream receives the native PascalCase method,
unlowered params and an explicit A2A-Version header, not the 0.3 wire."""
from litellm.proxy._types import UserAPIKeyAuth
monkeypatch.setattr(litellm, "disable_aiohttp_transport", True)
upstream: Final = respx_mock.post("http://backend-agent:10001").mock(
return_value=httpx.Response(404, content=upstream_body)
)
events: Final = [
event
async for event in _a2a_sse_event_source(
"http://backend-agent:10001",
{"jsonrpc": "2.0", "id": "req-1", "method": "tasks/resubscribe"},
request_id="req-1",
)
]
assert json.dumps(events, sort_keys=True) == json.dumps([relayed_event], sort_keys=True), upstream_body
assert json.loads(upstream.calls.last.request.content) == {
upstream_response = {
"jsonrpc": "2.0",
"id": "req-1",
"method": "tasks/resubscribe",
"result": {"id": "task-1", "status": {"state": "completed"}},
}
agent = _make_agent_mock()
agent.agent_card_params["protocolVersion"] = "1.0"
mock_request = _make_request_mock("GetTask", {"id": "task-1"})
mock_http_response = MagicMock()
mock_http_response.json.return_value = upstream_response
mock_http_response.is_success = True
mock_http_response.raise_for_status = MagicMock()
mock_handler = MagicMock()
mock_handler.post = AsyncMock(return_value=mock_http_response)
mock_handler.client = MagicMock()
user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="u1", team_id="t1")
with ExitStack() as stack:
for p in _base_patches(agent):
stack.enter_context(p)
stack.enter_context(
patch(
"litellm.llms.custom_httpx.http_handler.get_async_httpx_client",
return_value=mock_handler,
)
)
from litellm.proxy.agent_endpoints.a2a_endpoints import invoke_agent_a2a
response = await invoke_agent_a2a(
agent_id="test-agent",
request=mock_request,
fastapi_response=MagicMock(),
user_api_key_dict=user_api_key_dict,
)
body = json.loads(response.body.decode())
assert body["jsonrpc"] == "2.0"
assert body["result"]["id"] == "task-1"
posted = mock_handler.post.call_args
assert posted is not None
forwarded_body = posted.kwargs.get("json") or posted.args[1]
assert forwarded_body["method"] == "GetTask", "a 1.0 upstream must receive the native PascalCase method"
assert forwarded_body["params"] == {"id": "task-1"}, "1.0 params must not be lowered to the 0.3 wire"
headers = posted.kwargs.get("headers") or {}
assert headers.get("A2A-Version") == "1.0", "the negotiated 1.0 version must be advertised upstream"
@pytest.mark.asyncio
async def test_task_forward_0_3_upstream_keeps_legacy_wire():
"""#44531: a 0.3-configured upstream keeps the legacy wire method and gains no
A2A-Version header, preserving existing 0.3 compatibility."""
from litellm.proxy._types import UserAPIKeyAuth
upstream_response = {
"jsonrpc": "2.0",
"id": "req-1",
"result": {"id": "task-1", "status": {"state": "completed"}},
}
agent = _make_agent_mock()
agent.agent_card_params["protocolVersion"] = "0.3"
mock_request = _make_request_mock("GetTask", {"id": "task-1"})
mock_http_response = MagicMock()
mock_http_response.json.return_value = upstream_response
mock_http_response.is_success = True
mock_http_response.raise_for_status = MagicMock()
mock_handler = MagicMock()
mock_handler.post = AsyncMock(return_value=mock_http_response)
mock_handler.client = MagicMock()
user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="u1", team_id="t1")
with ExitStack() as stack:
for p in _base_patches(agent):
stack.enter_context(p)
stack.enter_context(
patch(
"litellm.llms.custom_httpx.http_handler.get_async_httpx_client",
return_value=mock_handler,
)
)
from litellm.proxy.agent_endpoints.a2a_endpoints import invoke_agent_a2a
response = await invoke_agent_a2a(
agent_id="test-agent",
request=mock_request,
fastapi_response=MagicMock(),
user_api_key_dict=user_api_key_dict,
)
assert response.status_code == 200
posted = mock_handler.post.call_args
assert posted is not None
forwarded_body = posted.kwargs.get("json") or posted.args[1]
assert forwarded_body["method"] == "tasks/get", "a 0.3 upstream must keep the legacy wire method"
headers = posted.kwargs.get("headers") or {}
assert headers.get("A2A-Version") is None, "the 0.3 wire path must not advertise a version header"
@pytest.mark.asyncio
async def test_resubscribe_1_0_upstream_uses_pascal_method_and_version_header():
"""#44531: SubscribeToTask to a 1.0 upstream keeps the PascalCase method and
negotiates the version instead of lowering to the 0.3 wire."""
from litellm.proxy._types import UserAPIKeyAuth
agent = _make_agent_mock()
agent.agent_card_params["protocolVersion"] = "1.0"
mock_request = _make_request_mock("SubscribeToTask", {"id": "task-1"})
async def fake_aiter_lines():
yield 'data: {"jsonrpc":"2.0","id":"req-1","result":{"kind":"status-update"}}'
mock_resp = AsyncMock()
mock_resp.is_success = True
mock_resp.aiter_lines = fake_aiter_lines
mock_resp.aclose = AsyncMock()
mock_async_client = MagicMock()
mock_async_client.build_request = MagicMock(return_value=MagicMock())
mock_async_client.send = AsyncMock(return_value=mock_resp)
mock_handler = MagicMock()
mock_handler.client = mock_async_client
mock_handler.post = AsyncMock()
user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="u1", team_id="t1")
with ExitStack() as stack:
for p in _base_patches(agent):
stack.enter_context(p)
stack.enter_context(
patch(
"litellm.llms.custom_httpx.http_handler.get_async_httpx_client",
return_value=mock_handler,
)
)
from litellm.proxy.agent_endpoints.a2a_endpoints import invoke_agent_a2a
response = await invoke_agent_a2a(
agent_id="test-agent",
request=mock_request,
fastapi_response=MagicMock(),
user_api_key_dict=user_api_key_dict,
)
async for _ in response.body_iterator:
pass
built = mock_async_client.build_request.call_args
assert built is not None
forwarded_body = built.kwargs.get("json") or built.args[1]
assert forwarded_body["method"] == "SubscribeToTask", "a 1.0 upstream must receive the native PascalCase method"
headers = built.kwargs.get("headers") or {}
assert headers.get("A2A-Version") == "1.0", "the negotiated 1.0 version must be advertised upstream"
@pytest.mark.asyncio
async def test_push_notification_config_1_0_envelope_is_validated_and_forwarded():
"""#44531: a 1.0 CreateTaskPushNotificationConfig uses the 1.0 params envelope
({id, config}) which the validation must accept and forward unlowered."""
from litellm.proxy._types import UserAPIKeyAuth
upstream_response = {
"jsonrpc": "2.0",
"id": "req-1",
"result": {"id": "task-1", "status": {"state": "completed"}},
}
agent = _make_agent_mock()
agent.agent_card_params["protocolVersion"] = "1.0"
params = {"id": "task-1", "config": {"url": "https://webhook.example.com"}}
mock_request = _make_request_mock("CreateTaskPushNotificationConfig", params)
mock_http_response = MagicMock()
mock_http_response.json.return_value = upstream_response
mock_http_response.is_success = True
mock_http_response.raise_for_status = MagicMock()
mock_handler = MagicMock()
mock_handler.post = AsyncMock(return_value=mock_http_response)
mock_handler.client = MagicMock()
user_api_key_dict = UserAPIKeyAuth(api_key="sk-test", user_id="u1", team_id="t1")
with ExitStack() as stack:
for p in _base_patches(agent):
stack.enter_context(p)
stack.enter_context(
patch(
"litellm.llms.custom_httpx.http_handler.get_async_httpx_client",
return_value=mock_handler,
)
)
stack.enter_context(
patch(
"litellm.proxy.agent_endpoints.a2a_endpoints.validate_url",
return_value=("https://webhook.example.com", "webhook.example.com"),
)
)
from litellm.proxy.agent_endpoints.a2a_endpoints import invoke_agent_a2a
response = await invoke_agent_a2a(
agent_id="test-agent",
request=mock_request,
fastapi_response=MagicMock(),
user_api_key_dict=user_api_key_dict,
)
body = json.loads(response.body.decode())
assert "error" not in body, f"the 1.0 push config envelope must validate, got: {body}"
posted = mock_handler.post.call_args
assert posted is not None
forwarded_body = posted.kwargs.get("json") or posted.args[1]
assert forwarded_body["method"] == "CreateTaskPushNotificationConfig"
assert forwarded_body["params"] == params, "1.0 params must not be lowered to the 0.3 wire"