BerriAI/litellm · error · ImportError

The 'a2a' package is required for A2A agent invocation…

Error message

The 'a2a' package is required for A2A agent invocation. Install it with: pip install a2a-sdk

What it means

LiteLLM's A2A support converts between its compat types and a2a-sdk 1.x protocol types through a conversions module loaded at import time. If the a2a package could not be imported, _a2a_conversions is None and the non-streaming _send_message raises this ImportError on the first agent call. a2a-sdk is an optional dependency (litellm's extra_proxy extra), not installed with base litellm.

Solutions

  1. pip install a2a-sdk, or pip install 'litellm[extra_proxy]' which pins a2a-sdk>=1.1.0,<2.0
  2. Verify the exact import litellm needs: python -c "from a2a.compat.v0_3 import conversions"
  3. If that import fails with the package present, pin a compatible version: pip install 'a2a-sdk>=1.1.0,<2.0' --force-reinstall

Example fix

# before
pip install litellm
await asend_message(api_base=..., request=req)  # ImportError

# after
pip install 'litellm[extra_proxy]'  # brings a2a-sdk
Defensive patterns

Strategy: try-catch

Validate before calling

try:
    from a2a.compat.v0_3 import conversions  # noqa: F401
except ImportError:
    raise SystemExit(
        'a2a-sdk missing or incompatible: pip install "litellm[extra_proxy]"'
    )

Try / catch

try:
    resp = await asend_message(api_base=api_base, request=req)
except ImportError as e:
    if 'a2a-sdk' in str(e):
        raise SystemExit('A2A requires a2a-sdk: pip install a2a-sdk') from e
    raise

Prevention

When it happens

Trigger: Calling asend_message (or routing a completion to an A2A agent) on an install without a2a-sdk; or with an a2a-sdk version that installs but lacks a2a.compat.v0_3.conversions, leaving _a2a_conversions None.

Common situations: Using agent providers (langgraph platform, agentcore) routed over A2A on slim installs; pip resolving an incompatible a2a-sdk version; Docker images built from bare 'pip install litellm'.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/d80ea484c5813631. Report an issue: GitHub.

Appendix: source

Thrown at litellm/a2a_protocol/main.py:248

def _to_core_send_message_request(request: "SendMessageRequest") -> "CoreSendMessageRequest":
    from a2a.compat.v0_3 import conversions

    return conversions.to_core_send_message_request(request)


def _to_compat_stream_response(
    event: "CoreStreamResponse", request_id: str | int
) -> "SendStreamingMessageSuccessResponse":
    from a2a.compat.v0_3 import conversions

    return conversions.to_compat_stream_response(event, request_id=request_id)


async def _send_message(a2a_client: "A2AClientType", request: "SendMessageRequest") -> "SendMessageResponse":
    """Send a non-streaming message via a2a-sdk 1.x and return JSON-RPC response."""
    if _a2a_conversions is None:
        raise ImportError(
            "The 'a2a' package is required for A2A agent invocation. Install it with: pip install a2a-sdk"
        )

    pb_request: Final = _to_core_send_message_request(request)
    last_event = None
    async for event in a2a_client.send_message(pb_request, context=_get_a2a_call_context(a2a_client)):
        last_event = event
    if last_event is None:
        raise RuntimeError("A2A send_message failed: no response received from agent.")

    stream_compat: Final = _to_compat_stream_response(last_event, request_id=request.id)
    result: Final = stream_compat.result
    if not isinstance(result, (Message, Task)):
        raise RuntimeError(
            "A2A send_message failed: non-streaming message/send expects the "
            "agent's final event to be a Message or Task result."
        )
    return SendMessageResponse(

View on GitHub (pinned to 77b7c6c40c)