BerriAI/litellm · error · Exception

api_base is required for A2A provider. Either provide api_ba

Error message

api_base is required for A2A provider. Either provide api_base parameter, set A2A_API_BASE environment variable, or register the agent in the proxy with model='a2a/<agent-name>'.

What it means

Exception raised on the A2A (agent-to-agent) provider path when no target agent URL could be determined: the registry lookup resolve_agent_config_from_registry returned nothing (agent not registered), and api_base, litellm.api_base, and A2A_API_BASE are all unset. A2A calls need the remote agent's endpoint to know where to send the message.

Source

Thrown at litellm/main.py:2102

    timeout: Final = ctx.timeout

    (
        api_base,
        api_key,
        headers,
    ) = litellm.A2AConfig.resolve_agent_config_from_registry(
        model=model,
        api_base=api_base,
        api_key=api_key,
        headers=headers,
        optional_params=optional_params,
    )

    # Fall back to environment variables and defaults
    api_base = api_base or litellm.api_base or get_secret_str("A2A_API_BASE")

    if api_base is None:
        raise Exception(
            "api_base is required for A2A provider. "
            "Either provide api_base parameter, set A2A_API_BASE environment variable, "
            "or register the agent in the proxy with model='a2a/<agent-name>'."
        )

    headers = headers or litellm.headers

    return base_llm_http_handler.completion(
        model=model,
        stream=stream,
        messages=messages,
        acompletion=acompletion,
        api_base=api_base,
        model_response=model_response,
        optional_params=optional_params,
        litellm_params=litellm_params,
        shared_session=shared_session,
        custom_llm_provider=custom_llm_provider,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Pass api_base pointing directly at the remote agent's A2A endpoint URL
2. Or export A2A_API_BASE with that endpoint
3. Or register the agent in the LiteLLM proxy and call it as model='a2a/<registered-name>' so the registry resolves it
4. Check the model string name exactly matches the registry key if you intended registry resolution

Example fix

# before
resp = litellm.completion(model='a2a/my-agent', messages=m)  # Exception

# after
import os
os.environ['A2A_API_BASE'] = 'https://agent.example.com/a2a/v1/agent'
resp = litellm.completion(model='a2a/my-agent', messages=m)

import os
if model.startswith('a2a/') and not (api_base or os.getenv('A2A_API_BASE') or agent_in_registry(model)):
    raise SystemExit(f'No endpoint for {model!r}: pass api_base, set A2A_API_BASE, or register the agent')

def a2a_target_resolved(model: str, api_base: str | None, registered: set[str]) -> bool:
    return not model.startswith('a2a/') or bool(api_base or os.getenv('A2A_API_BASE') or model.split('/', 1)[-1] in registered)

try:
    resp = litellm.completion(model='a2a/my-agent', messages=m)
except Exception as e:
    if 'api_base is required for A2A' in str(e):
        raise RuntimeError('Register the agent in the proxy or set A2A_API_BASE') from e
    raise

When it happens

Trigger: completion(model='a2a/<name-or-url>', ...) where the agent is not in the proxy registry, no api_base kwarg is given, and A2A_API_BASE is not exported.

Common situations: Using the a2a/ route in plain SDK code (registry only exists in the proxy); agent registered in proxy config under a different name than the one in the model string; env var missing in the container running the caller.

Related errors

• Azure AI Agents requests require an api_base. Set `api_base`
• api_base is required for Azure OpenAI LLM provider. Either s
• Azure Anthropic requests require an api_base. Set `api_base`
• No API Base provided for Azure OpenAI LLM provider. Set 'AZU
• 🚨🚨🚨 DISABLING LLM API ENDPOINTS is an Enterprise feature

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