Skip to content

The fastest, litest AI Gateway. Rust core with Python SDK. Call 100+ LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]

16.1 KB
Raw Blame
"""Per-agent ``litellm_params.a2a_protocol_version`` pins the A2A transport the proxy speaks to the agent.

langgraph-api 0.15 serves cards declaring ``JSONRPC``/``1.0`` while answering in the 0.3 ``kind`` dialect, so
a2a-sdk picks its strict v1 transport and rejects every reply. Pinning "0.3" routes the SDK onto its v0.3
compat transport; pinning "1.0" keeps v1 even where the mis-cased-binding fingerprint would downgrade.
Every cell asserts the caller's response, the exact request the scripted agent received, and Postgres.
"""

from __future__ import annotations

import json
import os
import time
from typing import Final

import pytest
from integration._support.client import Gateway, eventually
from integration._support.database import read_rows
from integration._support.ports import allocate_port
from integration.compatibility._a2a_peers import (
    HINT,
    KIND_ERROR,
    legacy_send,
    peer,
    posts,
    register,
    spend_rows,
    sse_frames,
)
from pydantic import JsonValue

from litellm.constants import PROXY_CONFIG_RELOAD_INTERVAL_SECONDS

PROXY_WORKERS: Final = int(os.environ.get("INTEGRATION_PROXY_WORKERS", "1"))
WORKER_SYNC_SECONDS: Final = 0.0 if PROXY_WORKERS == 1 else PROXY_CONFIG_RELOAD_INTERVAL_SECONDS + 5.0
FRESH_CONNECTION: Final = {"Connection": "close"}
PINNED: Final = {"a2a_protocol_version": "0.3"}
ROUTES: Final = ("/a2a/{id}", "/a2a/{id}/message/send", "/v1/a2a/{id}/message/send")


def _artifact_text(result: dict[str, JsonValue]) -> str:
    task: Final = result.get("task", result)
    assert isinstance(task, dict), result
    artifacts: Final = task["artifacts"]
    assert isinstance(artifacts, list) and len(artifacts) == 1, result
    parts: Final = artifacts[0]["parts"]  # type: ignore[index]
    return str(parts[0]["text"])  # type: ignore[index]


def _assert_legacy_wire(sent: tuple[dict[str, JsonValue], ...], marker: str, method: str = "message/send") -> None:
    assert len(sent) == 1, sent
    assert sent[0]["method"] == method, sent
    message: Final = sent[0]["params"]["message"]  # type: ignore[index]
    assert message["kind"] == "message" and message["role"] == "user", sent
    assert message["parts"] == [{"kind": "text", "text": "synthetic ping"}], sent
    assert message["messageId"] == marker + "-in", sent


def _assert_v1_wire(sent: tuple[dict[str, JsonValue], ...], marker: str, method: str = "SendMessage") -> None:
    assert len(sent) == 1, sent
    assert sent[0]["method"] == method, sent
    message: Final = sent[0]["params"]["message"]  # type: ignore[index]
    assert "kind" not in message and message["role"] == "ROLE_USER", sent
    assert message["parts"] == [{"text": "synthetic ping"}], sent
    assert message["messageId"] == marker + "-in", sent


def _one_spend_row(request_id: str, call_type: str, status: str) -> None:
    rows: Final = eventually(lambda: spend_rows(request_id), lambda values: len(values) == 1, seconds=70)
    assert rows[0]["call_type"] == call_type and rows[0]["status"] == status, rows


def _send_ok(gateway: Gateway, identity: str, marker: str, path: str = "/a2a/{id}") -> dict[str, JsonValue]:
    response: Final = gateway.request("POST", path.format(id=identity), legacy_send(marker))
    assert response.status_code == 200, response.text
    body: Final = response.json()
    assert body["id"] == marker and "error" not in body, response.text
    assert _artifact_text(body["result"]) == "echo: synthetic ping", response.text
    return body


def _send_kind_error(gateway: Gateway, identity: str, marker: str) -> str:
    response: Final = gateway.request("POST", f"/a2a/{identity}", legacy_send(marker))
    assert response.status_code == 500, response.text
    message: Final = str(response.json()["error"]["message"])
    assert KIND_ERROR in message, response.text
    return message


@pytest.mark.parametrize("route", ROUTES)
def test_pinned_langgraph_agent_answers_message_send_in_the_legacy_dialect(gateway: Gateway, route: str) -> None:
    with peer("lgsend", "langgraph") as agent, gateway.scenario() as scenario:
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, PINNED)
        _send_ok(gateway, identity, agent.marker, route)
        _assert_legacy_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        _one_spend_row(agent.marker, "asend_message", "success")


def test_pinned_langgraph_agent_streams_message_stream_to_the_final_frame(gateway: Gateway) -> None:
    with peer("lgstream", "langgraph") as agent, gateway.scenario() as scenario:
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, PINNED)
        response: Final = gateway.request(
            "POST", f"/a2a/{identity}", legacy_send(agent.marker, method="message/stream")
        )
        assert response.status_code == 200, response.text
        assert response.headers["content-type"].startswith("text/event-stream"), response.headers
        frames: Final = sse_frames(response.text)
        assert all(frame["id"] == agent.marker and "error" not in frame for frame in frames), response.text
        results: Final = [frame["result"] for frame in frames]
        assert len(results) == 3, response.text
        assert results[0]["statusUpdate"]["status"]["state"] == "TASK_STATE_WORKING", response.text  # type: ignore[index]
        assert results[0]["statusUpdate"]["status"]["message"]["parts"] == [{"text": "echo: synthetic ping"}]  # type: ignore[index]
        assert results[1]["artifactUpdate"]["artifact"]["parts"] == [{"text": "echo: synthetic ping"}]  # type: ignore[index]
        assert results[2]["statusUpdate"]["status"]["state"] == "TASK_STATE_COMPLETED", response.text  # type: ignore[index]
        _assert_legacy_wire(posts(agent.wire), agent.marker, "message/stream")  # type: ignore[arg-type]
        _one_spend_row(agent.marker, "asend_message_streaming", "success")


def test_v1_caller_reaches_pinned_legacy_agent_in_its_own_envelope(gateway: Gateway) -> None:
    with peer("lgv1caller", "langgraph") as agent, gateway.scenario() as scenario:
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, PINNED)
        response: Final = gateway.client.post(
            f"/a2a/{identity}",
            headers={"Authorization": f"Bearer {gateway.key}", "a2a-version": "1.0"},
            json={
                "jsonrpc": "2.0",
                "id": agent.marker,
                "method": "SendMessage",
                "params": {
                    "message": {
                        "role": "ROLE_USER",
                        "messageId": agent.marker + "-in",
                        "parts": [{"text": "synthetic ping"}],
                    }
                },
            },
        )
        assert response.status_code == 200, response.text
        body: Final = response.json()
        assert body["id"] == agent.marker and "error" not in body, response.text
        task: Final = body["result"]["task"]
        assert "kind" not in task and task["status"]["state"] == "TASK_STATE_COMPLETED", response.text
        assert task["artifacts"][0]["parts"] == [{"text": "echo: synthetic ping"}], response.text
        _assert_legacy_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        _one_spend_row(agent.marker, "asend_message", "success")


@pytest.mark.parametrize("value", ("0.3.0", 0.3, " 0.3 "), ids=("dotted", "number", "spaced"))
def test_protocol_version_aliases_pin_the_legacy_transport(gateway: Gateway, value: JsonValue) -> None:
    with peer("lgalias", "langgraph") as agent, gateway.scenario() as scenario:
        identity: Final = register(
            gateway, scenario.cleanups.callback, agent.marker, agent.url, {"a2a_protocol_version": value}
        )
        _send_ok(gateway, identity, agent.marker)
        _assert_legacy_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        _one_spend_row(agent.marker, "asend_message", "success")


def test_genuine_v1_agent_pinned_one_point_zero_is_unchanged(gateway: Gateway) -> None:
    with peer("v1pinned", "v1") as agent, gateway.scenario() as scenario:
        identity: Final = register(
            gateway, scenario.cleanups.callback, agent.marker, agent.url, {"a2a_protocol_version": "1.0"}
        )
        _send_ok(gateway, identity, agent.marker)
        _assert_v1_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        _one_spend_row(agent.marker, "asend_message", "success")


def test_genuine_v1_agent_unpinned_is_unchanged(gateway: Gateway) -> None:
    with peer("v1plain", "v1") as agent, gateway.scenario() as scenario:
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, None)
        _send_ok(gateway, identity, agent.marker)
        _assert_v1_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        _one_spend_row(agent.marker, "asend_message", "success")


@pytest.mark.parametrize("pin", (None, "0.3"), ids=("unpinned", "pinned-legacy"))
def test_lowercase_binding_still_downgrades_to_the_legacy_transport(gateway: Gateway, pin: str | None) -> None:
    with (
        peer("lglower", "langgraph", interfaces=[{"protocolBinding": "jsonrpc"}]) as agent,
        gateway.scenario() as scenario,
    ):
        params: Final = None if pin is None else {"a2a_protocol_version": pin}
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, params)
        _send_ok(gateway, identity, agent.marker)
        _assert_legacy_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        _one_spend_row(agent.marker, "asend_message", "success")


def test_explicit_one_point_zero_opts_out_of_the_lowercase_downgrade(gateway: Gateway) -> None:
    with peer("v1lower", "v1", interfaces=[{"protocolBinding": "jsonrpc"}]) as agent, gateway.scenario() as scenario:
        identity: Final = register(
            gateway, scenario.cleanups.callback, agent.marker, agent.url, {"a2a_protocol_version": "1.0"}
        )
        _send_ok(gateway, identity, agent.marker)
        _assert_v1_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        _one_spend_row(agent.marker, "asend_message", "success")


def test_one_point_zero_pin_on_a_legacy_card_sends_v1(gateway: Gateway) -> None:
    legacy_card: Final = [{"protocolBinding": "JSONRPC", "protocolVersion": "0.3"}]
    with peer("v1oncard03", "v1", interfaces=legacy_card) as agent, gateway.scenario() as scenario:
        identity: Final = register(
            gateway, scenario.cleanups.callback, agent.marker, agent.url, {"a2a_protocol_version": "1.0"}
        )
        _send_ok(gateway, identity, agent.marker)
        _assert_v1_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        _one_spend_row(agent.marker, "asend_message", "success")


def test_override_rewrites_only_canonical_interfaces(gateway: Gateway) -> None:
    with peer("lgmulti", "langgraph") as agent, peer("lgdecoy", "langgraph") as decoy, gateway.scenario() as scenario:
        agent.interfaces = [
            {"protocolBinding": "JSONRPC", "url": agent.url},
            {"protocolBinding": "custom-ws", "url": decoy.url},
            {"protocolBinding": "HTTP+JSON", "url": decoy.url},
        ]
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, PINNED)
        _send_ok(gateway, identity, agent.marker)
        _assert_legacy_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        assert decoy.wire.drain() == (), "the HTTP+JSON and custom bindings must not be selected"  # type: ignore[union-attr]
        _one_spend_row(agent.marker, "asend_message", "success")


def test_override_added_and_removed_by_patch_takes_effect_on_both_workers(gateway: Gateway) -> None:
    with peer("lgpatch", "langgraph") as agent, gateway.scenario() as scenario:
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, None)
        assert HINT in _send_kind_error(gateway, identity, agent.marker + "-before")
        before: Final = posts(agent.wire)  # type: ignore[arg-type]
        assert [item["method"] for item in before] == ["SendMessage"], before

        def send(suffix: str) -> int:
            response: Final = gateway.request(
                "POST", f"/a2a/{identity}", legacy_send(agent.marker + suffix), headers=FRESH_CONNECTION
            )
            return response.status_code

        def settle(params: dict[str, JsonValue], expected: int) -> None:
            patched: Final = gateway.request("PATCH", f"/v1/agents/{identity}", {"litellm_params": params})
            assert patched.status_code == 200, patched.text
            assert patched.json()["litellm_params"].get("a2a_protocol_version") == params.get("a2a_protocol_version")
            written_at: Final = time.monotonic()
            counter = iter(range(10_000))
            eventually(
                lambda: (time.monotonic() - written_at, tuple(send(f"-{next(counter)}") for _ in range(4))),
                lambda stamped: stamped[0] >= WORKER_SYNC_SECONDS and set(stamped[1]) == {expected},
                seconds=WORKER_SYNC_SECONDS + 30,
            )
            agent.wire.drain()  # type: ignore[union-attr]

        settle(dict(PINNED), 200)
        response: Final = gateway.request("POST", f"/a2a/{identity}", legacy_send(agent.marker))
        assert response.status_code == 200, response.text
        _assert_legacy_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]
        settle({}, 500)
        assert HINT in _send_kind_error(gateway, identity, agent.marker + "-after")


def test_repeated_pinned_sends_log_one_row_each(gateway: Gateway) -> None:
    with peer("lgrepeat", "langgraph") as agent, gateway.scenario() as scenario:
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, PINNED)
        markers: Final = tuple(f"{agent.marker}-{index}" for index in range(10))
        for marker in markers:
            response = gateway.request("POST", f"/a2a/{identity}", legacy_send(marker))
            assert response.status_code == 200 and response.json()["id"] == marker, response.text
        sent: Final = posts(agent.wire)  # type: ignore[arg-type]
        assert [item["params"]["message"]["messageId"] for item in sent] == [m + "-in" for m in markers], sent  # type: ignore[index]
        assert len({item["id"] for item in sent}) == len(markers), sent
        assert {item["method"] for item in sent} == {"message/send"}, sent
        for marker in markers:
            _one_spend_row(marker, "asend_message", "success")


def test_registered_agent_persists_protocol_version(gateway: Gateway) -> None:
    with peer("lgstored", "langgraph") as agent, gateway.scenario() as scenario:
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, PINNED)
        assert gateway.get(f"/v1/agents/{identity}")["litellm_params"]["a2a_protocol_version"] == "0.3"  # type: ignore[index]
        rows: Final = read_rows('SELECT litellm_params FROM "LiteLLM_AgentsTable" WHERE agent_id=%s', (identity,))
        assert len(rows) == 1, rows
        stored: Final = rows[0]["litellm_params"]
        stored_params: Final = json.loads(stored) if isinstance(stored, str) else stored
        assert stored_params["a2a_protocol_version"] == "0.3", rows  # type: ignore[index]
        _send_ok(gateway, identity, agent.marker)
        _assert_legacy_wire(posts(agent.wire), agent.marker)  # type: ignore[arg-type]


def test_pinned_agent_survives_localhost_retry(gateway: Gateway) -> None:
    dead: Final = f"http://localhost:{allocate_port()}/a2a/unreachable"
    with peer("lgretry", "langgraph", card_url=dead) as agent, gateway.scenario() as scenario:
        identity: Final = register(gateway, scenario.cleanups.callback, agent.marker, agent.url, PINNED)
        _send_ok(gateway, identity, agent.marker)
        traffic: Final = agent.wire.drain()  # type: ignore[union-attr]
        sent: Final = tuple(json.loads(item.body) for item in traffic if item.method == "POST")
        assert tuple(item.target for item in traffic if item.method == "POST") == ("/a2a/" + agent.marker + "/",), (
            traffic
        )
        _assert_legacy_wire(sent, agent.marker)
        _one_spend_row(agent.marker, "asend_message", "success")