BerriAI/litellm · error · ImportError

A2A SDK is required for localhost retry handling. Install…

Error message

A2A SDK is required for localhost retry handling. Install it with: pip install a2a-sdk

What it means

Retrying a failed A2A request whose agent card advertised a localhost URL requires rebuilding the client through the a2a-sdk, so handle_a2a_localhost_retry raises ImportError when the SDK is not importable (A2A_SDK_AVAILABLE is False). In a healthy install you rarely reach it because client creation fails earlier without the SDK; hitting it usually means a broken, partial, or version-drifted a2a-sdk install.

Solutions

  1. pip install a2a-sdk (or pip install 'litellm[extra_proxy]', which pins a2a-sdk>=1.1.0,<2.0) and restart the worker
  2. Verify: python -c "import a2a; print(a2a.__version__)"
  3. If the package is present but still failing, force-reinstall to repair a broken install: pip install --force-reinstall 'a2a-sdk>=1.1.0,<2.0'

Example fix

# before
pip install litellm  # a2a-sdk missing -> retry path dies with ImportError

# after
pip install 'litellm[extra_proxy]'  # includes a2a-sdk>=1.1.0,<2.0
Defensive patterns

Strategy: try-catch

Validate before calling

def a2a_sdk_available() -> bool:
    try:
        import a2a  # noqa: F401
        from a2a.compat.v0_3 import conversions  # noqa: F401
        return True
    except ImportError:
        return False


assert a2a_sdk_available(), 'pip install a2a-sdk before using A2A retries'

Try / catch

try:
    resp = await asend_message(a2a_client=client, request=req)
except ImportError as e:
    if 'a2a-sdk' in str(e):
        raise SystemExit('Install a2a-sdk (litellm[extra_proxy]) to use A2A') from e
    raise

Prevention

When it happens

Trigger: A localhost-URL retry is attempted on a host where 'import a2a' (or its compat layer) fails: SDK uninstalled after the client was built, a corrupted venv, or an a2a-sdk version that imports but lacks the pieces litellm expects.

Common situations: Slim production images omitting a2a-sdk; dependency downgrades removing the package mid-session; litellm and a2a-sdk versions drifting apart after a partial upgrade.

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/fad6aa11ba39375c. Report an issue: GitHub.

Appendix: source

Thrown at litellm/a2a_protocol/exception_mapping_utils.py:185

    Handle A2ALocalhostURLError by fixing the URL and creating a new client.

    This is called when we catch an A2ALocalhostURLError and want to retry
    with the corrected URL.

    Args:
        error: The localhost URL error
        agent_card: The agent card object to fix
        a2a_client: The current A2A client
        is_streaming: Whether this is a streaming request (for logging)

    Returns:
        A new A2A client with the fixed URL

    Raises:
        ImportError: If the A2A SDK is not installed
    """
    if not A2A_SDK_AVAILABLE:
        raise ImportError("A2A SDK is required for localhost retry handling. Install it with: pip install a2a-sdk")

    if agent_card is None:
        raise RuntimeError(
            "Cannot retry A2A localhost URL fix: no agent card is available to "
            "rewrite, so the upstream URL cannot be corrected."
        )

    request_type: Final = "streaming " if is_streaming else ""
    verbose_logger.warning(
        "A2A %srequest to '%s' failed: %s. Agent card contains localhost/internal URL. Retrying with base_url '%s'.",
        request_type,
        error.localhost_url,
        error.original_error,
        error.base_url,
    )

    # Fix the agent card URL
    set_agent_card_url(agent_card, error.base_url)

View on GitHub (pinned to 77b7c6c40c)