VectifyAI/PageIndex · error · PageIndexAPIError

responses() cannot drive '{model_name}': provider-prefixed m

Error message

responses() cannot drive '{model_name}': provider-prefixed models route through LiteLLM, which speaks chat.completions, not the Responses API. Use chat_completions() (or messages() for Anthropic models), or point OPENAI_BASE_URL at a Responses-capable backend and use a bare or 'openai/'-prefixed model name.

What it means

responses() speaks the OpenAI Responses API, but provider-prefixed model names (e.g. 'anthropic/claude-...', 'groq/...') route through LiteLLM, which only implements chat.completions. The library refuses the combination rather than failing opaquely at request time. 'openai/'-prefixed and bare names are allowed.

Source

Thrown at pageindex/local_chat.py:192

            "Agents SDK — "
            "pip install openai-agents. "
            "messages() runs on the anthropic extra instead."
        ) from exc


def _sdk_backend(backend) -> dict:
    """chat_backend for an SDK constructor: LiteLLM takes either endpoint
    spelling, the openai and anthropic SDKs only ``base_url``."""
    return {("base_url" if key == "api_base" else key): value
            for key, value in (backend or {}).items()}


def _openai_model(protocol: str, model_name: str, backend=None):
    """The backend protocol driver — the seam tests replace with a fake."""
    if protocol == "responses":
        model_name = model_name.removeprefix("litellm/")
        if "/" in model_name and not model_name.startswith("openai/"):
            raise PageIndexAPIError(
                f"responses() cannot drive '{model_name}': provider-prefixed "
                "models route through LiteLLM, which speaks chat.completions, "
                "not the Responses API. Use chat_completions() (or messages() "
                "for Anthropic models), or point OPENAI_BASE_URL at a "
                "Responses-capable backend and use a bare or "
                "'openai/'-prefixed model name."
            )
        import openai
        model_name = model_name.removeprefix("openai/")
        try:
            sdk_client = openai.AsyncOpenAI(**_sdk_backend(backend))
        except (openai.OpenAIError, TypeError) as exc:
            raise PageIndexAPIError(
                f"The OpenAI backend is not configured: {exc}") from exc
        # A caller-owned transport must survive the per-call close.
        sdk_client._pageindex_caller_http = "http_client" in (backend or {})
        from agents.models.openai_responses import OpenAIResponsesModel
        return OpenAIResponsesModel(model_name, openai_client=sdk_client)

View on GitHub (pinned to afb5e11976)

Solutions

1. Use chat_completions() for provider-prefixed models
2. For Anthropic models, use messages()
3. Or drop the prefix / use 'openai/...' and point OPENAI_BASE_URL at a Responses-capable backend

Example fix

# before
client.responses(model="anthropic/claude-sonnet-4", input=q)

# after
client.chat_completions(model="anthropic/claude-sonnet-4", messages=[{"role":"user","content":q}])

def engine_for(model: str) -> str:
    m = model.removeprefix('litellm/')
    return 'responses' if ('/' not in m or m.startswith('openai/')) else 'chat_completions'

def responses_compatible(model: str) -> bool:
    m = model.removeprefix('litellm/')
    return '/' not in m or m.startswith('openai/')

null

When it happens

Trigger: client.responses(model="anthropic/claude-sonnet-4", ...) or model="groq/llama-3" with responses().

Common situations: Copy-pasting LiteLLM-style model strings from docs, switching a working chat_completions call to responses() without changing the model name, using a gateway that expects provider prefixes.

Related errors

• Failed to delete document: Document not found.
• limit must be between 1 and 100
• offset must be non-negative
• Failed to list documents: folders are not supported in local
• doc_id must be a string or a list of strings.

AI-assisted analysis of VectifyAI/PageIndex@afb5e11976 (2026-08-27). Data as JSON: /api/errors/0f3541fe766c0b4f. Report an issue: GitHub.