From b86c227b807ca9055c0d6ae3b5aa0ab2eb00d21a Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 15 Nov 2026 05:23:35 +0000 Subject: [PATCH 1/3] feat(agents): name the exception and LiteLLM deployment when the Gemini proxy's upstream call fails --- .../agents/agents/gemini/a2a_server.py | 36 ++++++++++++++-- tst/unit/agents/gemini/test_litellm_proxy.py | 42 ++++++++++++++++++- 2 files changed, 73 insertions(+), 5 deletions(-) diff --git a/src/agent_env/agents/agents/gemini/a2a_server.py b/src/agent_env/agents/agents/gemini/a2a_server.py index acce2610e..98f9c6bf3 100644 --- a/src/agent_env/agents/agents/gemini/a2a_server.py +++ b/src/agent_env/agents/agents/gemini/a2a_server.py @@ -140,6 +140,34 @@ _LITELLM_PROXY_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH"] _PROXY_DROP_REQ_HEADERS = {"host", "content-length", "transfer-encoding", "connection", "keep-alive", "accept-encoding"} _PROXY_DROP_RESP_HEADERS = {"content-length", "transfer-encoding", "content-encoding", "connection", "keep-alive"} +_LITELLM_ROUTE_HEADERS = ("x-litellm-model-id", "x-litellm-model-api-base", "x-litellm-model-group") + + +def _describe_transport_error(exc: Exception) -> str: + """Name the exception class: many httpx errors (ReadTimeout, RemoteProtocolError) stringify to ''.""" + text = str(exc) + return f"{type(exc).__name__}: {text}" if text else repr(exc) + + +def _litellm_route_headers(headers: httpx.Headers) -> dict[str, str]: + """The headers by which LiteLLM names the deployment that served (or failed) a call, when it sent them.""" + return {name: headers[name] for name in _LITELLM_ROUTE_HEADERS if name in headers} + + +def _log_upstream_error(proxy: str, upstream: httpx.Response) -> None: + logger.warning( + "%s upstream %s: %s", proxy, upstream.status_code, upstream.text[:500], + extra={"event": "litellm_upstream_error_response", "proxy": proxy, + "upstream_status": upstream.status_code, **_litellm_route_headers(upstream.headers)}, + ) + + +def _log_transport_error(proxy: str, exc: Exception) -> str: + detail = _describe_transport_error(exc) + logger.warning("%s upstream request failed: %s", proxy, detail, + extra={"event": "litellm_upstream_transport_error", "proxy": proxy, + "error_type": type(exc).__name__}) + return detail class GeminiConfig(AgentConfig): @@ -347,9 +375,9 @@ async def _vertex_openai_bridge( headers=headers, content=json.dumps(oai_req).encode(), ) except httpx.HTTPError as e: - raise HTTPException(status_code=502, detail=f"vertex bridge upstream failed: {e}") + raise HTTPException(status_code=502, detail=f"vertex bridge upstream failed: {_log_transport_error('vertex bridge', e)}") if upstream.status_code >= 400: - logger.warning("vertex bridge upstream %s: %s", upstream.status_code, upstream.text[:500]) + _log_upstream_error("vertex bridge", upstream) return Response( content=upstream.content, status_code=upstream.status_code, media_type=upstream.headers.get("content-type", "application/json"), @@ -734,7 +762,9 @@ async def litellm_gemini_proxy(self, request: Request) -> Response: params=request.query_params, headers=fwd_headers, content=body, ) except httpx.HTTPError as e: - raise HTTPException(status_code=502, detail=f"gemini upstream request failed: {e}") + raise HTTPException(status_code=502, detail=f"gemini upstream request failed: {_log_transport_error('gemini', e)}") + if upstream.status_code >= 400: + _log_upstream_error("gemini", upstream) resp_headers = {k: v for k, v in upstream.headers.items() if k.lower() not in _PROXY_DROP_RESP_HEADERS} return Response(content=upstream.content, status_code=upstream.status_code, headers=resp_headers) diff --git a/tst/unit/agents/gemini/test_litellm_proxy.py b/tst/unit/agents/gemini/test_litellm_proxy.py index 1835c0679..d929f1f04 100644 --- a/tst/unit/agents/gemini/test_litellm_proxy.py +++ b/tst/unit/agents/gemini/test_litellm_proxy.py @@ -177,7 +177,45 @@ def test_an_unreachable_upstream_is_a_502(upstream, agent, client): response = client.post(GENERATE, content=b"{}") assert (response.status_code, response.json()) == ( - 502, {"detail": "gemini upstream request failed: All connection attempts failed"}) + 502, {"detail": "gemini upstream request failed: ConnectError: All connection attempts failed"}) + + +def test_an_exception_with_no_message_is_named_in_the_502_and_the_log(caplog, upstream, agent, client): + _route(agent) + upstream.response = httpx.ReadTimeout("") + + response = client.post(GENERATE, content=b"{}") + + assert response.status_code == 502 + assert response.json() == {"detail": "gemini upstream request failed: ReadTimeout('')"} + (record,) = [r for r in caplog.records if getattr(r, "event", None) == "litellm_upstream_transport_error"] + assert (record.proxy, record.error_type) == ("gemini", "ReadTimeout") + assert "ReadTimeout" in record.getMessage() + + +def test_an_unreachable_bridge_upstream_names_the_exception(vertex, client): + vertex.response = httpx.RemoteProtocolError("") + + response = client.post(GENERATE, json=_GREQ) + + assert response.json() == {"detail": "vertex bridge upstream failed: RemoteProtocolError('')"} + + +@pytest.mark.parametrize("path", ["passthrough", "bridge"]) +def test_an_error_response_logs_the_litellm_routing_headers_that_are_present(caplog, upstream, agent, client, path): + _route(agent, model="vertex_ai/global/g" if path == "bridge" else None) + upstream.response = httpx.Response( + 429, json={"error": "slow down"}, + headers={"x-litellm-model-id": "dep-1", "x-litellm-model-group": "grp", "x-litellm-response-cost": "0.1"}, + ) + + response = client.post(GENERATE, json=_GREQ) + + assert response.status_code == 429 + (record,) = [r for r in caplog.records if getattr(r, "event", None) == "litellm_upstream_error_response"] + assert record.upstream_status == 429 + assert (record.__dict__["x-litellm-model-id"], record.__dict__["x-litellm-model-group"]) == ("dep-1", "grp") + assert "x-litellm-model-api-base" not in record.__dict__ and "x-litellm-response-cost" not in record.__dict__ # ── provider-prefixed models: the chat-completions bridge ──────────────────────── @@ -245,7 +283,7 @@ def test_bridge_upstream_errors(vertex, client): assert (limited.status_code, limited.content) == (429, b'{"error":"slow down"}') assert (garbled.status_code, garbled.json()) == (502, {"detail": "vertex bridge: non-JSON upstream response"}) - assert (unreachable.status_code, unreachable.json()) == (502, {"detail": "vertex bridge upstream failed: refused"}) + assert (unreachable.status_code, unreachable.json()) == (502, {"detail": "vertex bridge upstream failed: ConnectError: refused"}) From 7f01034d87c3ee6588c553cda15981d9d68e4668 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 15 Nov 2026 05:54:24 +0000 Subject: [PATCH 2/3] Gemini proxy: put event name and routing headers in the log message --- src/agent_env/agents/agents/gemini/a2a_server.py | 9 ++++++--- tst/unit/agents/gemini/test_litellm_proxy.py | 7 +++++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/src/agent_env/agents/agents/gemini/a2a_server.py b/src/agent_env/agents/agents/gemini/a2a_server.py index 98f9c6bf3..9bb7c88f9 100644 --- a/src/agent_env/agents/agents/gemini/a2a_server.py +++ b/src/agent_env/agents/agents/gemini/a2a_server.py @@ -155,16 +155,19 @@ def _litellm_route_headers(headers: httpx.Headers) -> dict[str, str]: def _log_upstream_error(proxy: str, upstream: httpx.Response) -> None: + route = _litellm_route_headers(upstream.headers) + route_text = "".join(f" {name}={value}" for name, value in route.items()) logger.warning( - "%s upstream %s: %s", proxy, upstream.status_code, upstream.text[:500], + "%s upstream %s: %s event=litellm_upstream_error_response%s", + proxy, upstream.status_code, upstream.text[:500], route_text, extra={"event": "litellm_upstream_error_response", "proxy": proxy, - "upstream_status": upstream.status_code, **_litellm_route_headers(upstream.headers)}, + "upstream_status": upstream.status_code, **route}, ) def _log_transport_error(proxy: str, exc: Exception) -> str: detail = _describe_transport_error(exc) - logger.warning("%s upstream request failed: %s", proxy, detail, + logger.warning("%s upstream request failed: %s event=litellm_upstream_transport_error", proxy, detail, extra={"event": "litellm_upstream_transport_error", "proxy": proxy, "error_type": type(exc).__name__}) return detail diff --git a/tst/unit/agents/gemini/test_litellm_proxy.py b/tst/unit/agents/gemini/test_litellm_proxy.py index d929f1f04..4d6969f4d 100644 --- a/tst/unit/agents/gemini/test_litellm_proxy.py +++ b/tst/unit/agents/gemini/test_litellm_proxy.py @@ -191,6 +191,7 @@ def test_an_exception_with_no_message_is_named_in_the_502_and_the_log(caplog, up (record,) = [r for r in caplog.records if getattr(r, "event", None) == "litellm_upstream_transport_error"] assert (record.proxy, record.error_type) == ("gemini", "ReadTimeout") assert "ReadTimeout" in record.getMessage() + assert "event=litellm_upstream_transport_error" in record.getMessage() def test_an_unreachable_bridge_upstream_names_the_exception(vertex, client): @@ -214,8 +215,10 @@ def test_an_error_response_logs_the_litellm_routing_headers_that_are_present(cap assert response.status_code == 429 (record,) = [r for r in caplog.records if getattr(r, "event", None) == "litellm_upstream_error_response"] assert record.upstream_status == 429 - assert (record.__dict__["x-litellm-model-id"], record.__dict__["x-litellm-model-group"]) == ("dep-1", "grp") - assert "x-litellm-model-api-base" not in record.__dict__ and "x-litellm-response-cost" not in record.__dict__ + message = record.getMessage() + assert "event=litellm_upstream_error_response" in message + assert "x-litellm-model-id=dep-1" in message and "x-litellm-model-group=grp" in message + assert "x-litellm-model-api-base" not in message and "x-litellm-response-cost" not in message # ── provider-prefixed models: the chat-completions bridge ──────────────────────── From f9a6dada85594f042af02836dfc85fa134f4bcd1 Mon Sep 17 00:00:00 2001 From: Ubuntu Date: Sun, 15 Nov 2026 06:07:19 +0000 Subject: [PATCH 3/3] Gemini proxy: name the upstream error body log limit --- src/agent_env/agents/agents/gemini/a2a_server.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/agent_env/agents/agents/gemini/a2a_server.py b/src/agent_env/agents/agents/gemini/a2a_server.py index 9bb7c88f9..1d4bfacbb 100644 --- a/src/agent_env/agents/agents/gemini/a2a_server.py +++ b/src/agent_env/agents/agents/gemini/a2a_server.py @@ -137,6 +137,7 @@ # the CLI prints each model call's events once that call returns, so the live # trajectory advances per call. _LITELLM_PROXY_PATH = "/litellm-gemini" +_UPSTREAM_ERROR_BODY_LOG_LIMIT = 500 _LITELLM_PROXY_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH"] _PROXY_DROP_REQ_HEADERS = {"host", "content-length", "transfer-encoding", "connection", "keep-alive", "accept-encoding"} _PROXY_DROP_RESP_HEADERS = {"content-length", "transfer-encoding", "content-encoding", "connection", "keep-alive"} @@ -159,7 +160,7 @@ def _log_upstream_error(proxy: str, upstream: httpx.Response) -> None: route_text = "".join(f" {name}={value}" for name, value in route.items()) logger.warning( "%s upstream %s: %s event=litellm_upstream_error_response%s", - proxy, upstream.status_code, upstream.text[:500], route_text, + proxy, upstream.status_code, upstream.text[:_UPSTREAM_ERROR_BODY_LOG_LIMIT], route_text, extra={"event": "litellm_upstream_error_response", "proxy": proxy, "upstream_status": upstream.status_code, **route}, )