BerriAI/litellm · error · AzureAIAgentsError

{error_msg}: {response.text}

Error message

{error_msg}: {response.text}

What it means

The Azure AI Foundry Agents handler wraps every raw HTTP call (create thread, add message, create run, list messages) with _check_response. If the Azure service returns a status code outside the small expected list (usually [200]/[201]), it raises AzureAIAgentsError carrying the real HTTP status code and the untouched response body. The message format is '<operation>: <response.text>', e.g. 'Failed to get run status: {"error":{...}}'.

Source

Thrown at litellm/llms/azure_ai/agents/handler.py:233

        # Azure Foundry Agents uses Bearer token authentication
        # The api_key here is expected to be an Azure AD token
        if api_key:
            headers["Authorization"] = f"Bearer {api_key}"

        api_version: Final = optional_params.get("api_version", self.config.DEFAULT_API_VERSION)
        agent_id: Final = self.config._get_agent_id(model, optional_params)
        thread_id: Final = optional_params.get("thread_id")
        api_base = api_base.rstrip("/")

        verbose_logger.debug("Azure AI Agents completion - api_base: %s, agent_id: %s", api_base, agent_id)

        return headers, api_version, agent_id, thread_id, api_base

    def _check_response(self, response: httpx.Response, expected_codes: list[int], error_msg: str):
        """Check response status and raise error if not expected."""
        if response.status_code not in expected_codes:
            raise AzureAIAgentsError(
                status_code=response.status_code,
                message=f"{error_msg}: {response.text}",
            )

    # -------------------------------------------------------------------------
    # Sync Completion
    # -------------------------------------------------------------------------
    def completion(
        self,
        model: str,
        messages: list[dict[str, Any]],
        api_base: str,
        api_key: str,
        model_response: ModelResponse,
        logging_obj: LiteLLMLoggingObj,
        optional_params: dict,
        litellm_params: dict,
        timeout: float,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Read the status_code and response.text embedded in the exception message — they are the raw Azure error and pinpoint the failing step.
2. 401/403: refresh the Azure AD token or fix AZURE_TENANT_ID/AZURE_CLIENT_ID/AZURE_CLIENT_SECRET; if you got the token manually with az, re-run it.
3. 404: verify api_base points at your Foundry project endpoint and the agent id in model='azure_ai_agents/<agent_id>' exists.
4. 429: back off and retry; honor Retry-After from the failing response.

Example fix

# before
try:
    resp = litellm.completion(model='azure_ai_agents/my-agent', messages=msgs, api_base=..., api_key=...)
except AzureAIAgentsError as e:
    raise  # opaque crash

# after
except AzureAIAgentsError as e:
    if e.status_code in (401, 403):
        api_key = refresh_azure_token()  # az account get-access-token --resource https://ai.azure.com
    elif e.status_code == 429:
        time.sleep(5)
    else:
        logger.error('agents call failed: %s %s', e.status_code, e.message)

def is_azure_ai_agents_error(e: BaseException) -> bool:
    return type(e).__name__ == 'AzureAIAgentsError' and hasattr(e, 'status_code')

try:
    result = litellm.completion(model='azure_ai_agents/agent', ...)
except Exception as e:
    if type(e).__name__ == 'AzureAIAgentsError':
        if e.status_code in (429, 500, 503):
            await asyncio.sleep(backoff()); retry()
        elif e.status_code in (401, 403):
            refresh_token_and_retry_once()
        else:
            alert(f'agents failed {e.status_code}: {e.message}')
    raise

When it happens

Trigger: Any Azure AI Agents completion call where an underlying REST step fails: wrong or expired API key (401), wrong api_base/project endpoint (404), invalid agent id in the model string (404), throttling (429), or a malformed payload the service rejects (400). Also 'Failed to get messages' when the thread was deleted mid-run.

Common situations: Azure AD token expired (tokens from `az account get-access-token` last ~1h); using the wrong endpoint flavor (project endpoint vs. services.ai.azure.com); agent deleted in Azure AI Foundry portal but still referenced in code; api_version mismatch after Azure deprecated a preview version.

Related errors

• Streaming request failed: {error_text.decode()}
• api_key (Azure AD token) is required for Azure Foundry Agent
• Run {status}: {error_msg}
• Run timed out waiting for completion
• api_base is required for Azure AI Agents. Set it via AZURE_A

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