BerriAI/litellm · error · HTTPException

Agent '{agent_id}' not found

Error message

Agent '{agent_id}' not found

What it means

Raised in the A2A agent-card discovery endpoint when _get_agent() returns None for the requested agent_id — no in-memory registry entry and no database row match. The endpoint returns HTTP 404 (inside a try block that converts it to a JSON-RPC-style error where appropriate), telling the client the agent identifier is unknown to this proxy.

Source

Thrown at litellm/proxy/agent_endpoints/a2a_endpoints.py:536

):
    """
    Get the agent card for an agent (A2A discovery endpoint).

    Supports both standard paths:
    - /.well-known/agent-card.json
    - /.well-known/agent.json

    The URL in the agent card is rewritten to point to the LiteLLM proxy,
    so all subsequent A2A calls go through LiteLLM for logging and cost tracking.
    """
    from litellm.proxy.agent_endpoints.auth.agent_permission_handler import (
        AgentRequestHandler,
    )

    try:
        agent: Final = _get_agent(agent_id)
        if agent is None:
            raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")

        # Check agent permission (skip for admin users)
        is_allowed: Final = await AgentRequestHandler.is_agent_allowed(
            agent_id=agent.agent_id,
            user_api_key_auth=user_api_key_dict,
        )
        if not is_allowed:
            raise HTTPException(
                status_code=403,
                detail=f"Agent '{agent_id}' is not allowed for your key/team. Contact proxy admin for access.",
            )

        if not agent.agent_card_params:
            raise HTTPException(
                status_code=404,
                detail=f"Agent '{agent_id}' has no agent card configured",
            )

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Check the agent_id exists; list agents first.

Example fix

GET /agents to find valid IDs.

When it happens

Trigger: Thrown at litellm/proxy/agent_endpoints/a2a_endpoints.py:536 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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