BerriAI/litellm · error · HTTPException

Only proxy admins can discover agent cards. Your role={user_

Error message

Only proxy admins can discover agent cards. Your role={user_api_key_dict.user_role}

What it means

The /v1/a2a/discover endpoint is admin-only because it makes the proxy probe arbitrary caller-supplied URLs; non-admin roles are rejected 403 to prevent using the proxy to enumerate internal networks.

Source

Thrown at litellm/proxy/a2a/endpoints.py:92

    user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
) -> JSONResponse:
    """
    Fetch the upstream agent's well-known card so the UI can show the admin
    which skills/capabilities the agent exposes.

    Only proxy admins can call this — the UI uses it during agent registration,
    and we don't want arbitrary keys probing internal URLs.

    Example:
    ```bash
    curl -X POST "http://localhost:4000/v1/a2a/discover" \\
        -H "Authorization: Bearer <admin_key>" \\
        -H "Content-Type: application/json" \\
        -d '{"url": "https://upstream-agent.example.com"}'
    ```
    """
    if user_api_key_dict.user_role != LitellmUserRoles.PROXY_ADMIN:
        raise HTTPException(
            status_code=403,
            detail=(f"Only proxy admins can discover agent cards. Your role={user_api_key_dict.user_role}"),
        )

    try:
        card: Final = await fetch_well_known_card(
            request.url,
            discovery_mode=request.discovery_mode,
            params=request.params,
        )
    except AgentCardDiscoveryError as exc:
        raise HTTPException(status_code=400, detail=str(exc))
    except Exception as exc:
        verbose_proxy_logger.exception("Unexpected error during A2A discovery: %s", exc)
        raise HTTPException(status_code=500, detail=f"Discovery failed: {exc}")

    return JSONResponse(
        content={"url": request.url, "agent_card": card},

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Use a key with the PROXY_ADMIN role to discover agent cards.

Example fix

Retry with an admin key.

When it happens

Trigger: Thrown at litellm/proxy/a2a/endpoints.py:92 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/83d7b325adb016e0. Report an issue: GitHub.