BerriAI/litellm · error · ValueError

api_base is required for Azure AI Agents. Set it via AZURE_A

Error message

api_base is required for Azure AI Agents. Set it via AZURE_AI_API_BASE env var or api_base parameter.

What it means

The Azure AI Agents transformation builds operation URLs (threads, messages, runs) from a base URL. If api_base resolves to None — neither passed as a parameter nor via AZURE_AI_API_BASE — it raises this ValueError before any request is made. Azure AI Foundry has no default regional endpoint LiteLLM can infer, so the base URL is mandatory.

Source

Thrown at litellm/llms/azure_ai/agents/transformation.py:163

        api_base: str | None,
        api_key: str | None,
        model: str,
        optional_params: dict,
        litellm_params: dict,
        stream: bool | None = None,
    ) -> str:
        """
        Get the base URL for Azure AI Agent Service.

        The actual endpoint will vary based on the operation:
        - /openai/threads for creating threads
        - /openai/threads/{thread_id}/messages for adding messages
        - /openai/threads/{thread_id}/runs for creating runs

        This returns the base URL that will be modified for each operation.
        """
        if api_base is None:
            raise ValueError(
                "api_base is required for Azure AI Agents. Set it via AZURE_AI_API_BASE env var or api_base parameter."
            )

        # Remove trailing slash if present
        api_base = api_base.rstrip("/")

        # Return base URL - actual endpoints will be constructed during request
        return api_base

    def _get_agent_id(self, model: str, optional_params: dict) -> str:
        """
        Get the agent ID from model or optional_params.

        model format: "azure_ai/agents/<agent_id>" or "agents/<agent_id>" or just "<agent_id>"
        """
        agent_id: Final = optional_params.get("agent_id") or optional_params.get("assistant_id")
        if agent_id:
            return agent_id

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Pass api_base explicitly: litellm.completion(model='azure_ai_agents/<agent>', api_base='https://<resource>.services.ai.azure.com/api/projects/<proj>', api_key=..., messages=...).
  2. Or export AZURE_AI_API_BASE in the runtime environment of the process calling litellm.
  3. Verify the value with a curl to {api_base}/openai/threads to prove the base URL is reachable before blaming litellm.
  4. In proxy config, set api_base on the deployment's litellm_params, not at top level.

Example fix

# before
os.environ['AZURE_API_BASE'] = 'https://x.services.ai.azure.com'  # wrong var
litellm.completion(model='azure_ai_agents/agent1', messages=m, api_key=k)

# after
litellm.completion(
    model='azure_ai_agents/agent1', messages=m, api_key=k,
    api_base='https://x.services.ai.azure.com/api/projects/proj1',
)
Defensive patterns

Strategy: validation

Validate before calling

import os

def agents_api_base() -> str:
    base = os.getenv('AZURE_AI_API_BASE')
    if not base:
        raise RuntimeError('AZURE_AI_API_BASE must be set for azure_ai_agents calls')
    return base

Try / catch

try:
    litellm.completion(model='azure_ai_agents/agent', api_base=agents_api_base(), ...)
except ValueError as e:
    if 'AZURE_AI_API_BASE' in str(e):
        raise ConfigurationError(str(e)) from e
    raise

Prevention

When it happens

Trigger: Calling completion on an azure_ai_agents model without api_base and without the AZURE_AI_API_BASE env var; setting it under a different name (AZURE_API_BASE is a different provider's variable); passing None explicitly via litellm_params.

Common situations: Config written for Azure OpenAI (AZURE_API_BASE) reused for Foundry agents; env var defined in .env locally but not in the deployed container; typo in the variable name in docker-compose or CI secrets.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/2065fdc0d2a9671e. Report an issue: GitHub.