VectifyAI/PageIndex · error · PageIndexAPIError

{method} with your own chat model requires the OpenAI Agents

Error message

{method} with your own chat model requires the OpenAI Agents SDK — pip install openai-agents. messages() runs on the anthropic extra instead.

What it means

chat_completions() and responses() with your own chat model are implemented on top of the OpenAI Agents SDK; if `import agents` fails, this error tells you to install it. messages() does not need it (it uses the anthropic extra).

Source

Thrown at pageindex/local_chat.py:172

    try:
        while True:
            item = items.get()
            if item is _SENTINEL:
                return
            if isinstance(item, BaseException):
                raise item
            yield item
    finally:
        cancelled.set()


# ── OpenAI engine (chat_completions / responses) ──

def _require_openai_agents(method: str) -> None:
    try:
        import agents  # noqa: F401
    except ImportError as exc:
        raise PageIndexAPIError(
            f"{method} with your own chat model requires the OpenAI "
            "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/")

View on GitHub (pinned to afb5e11976)

Solutions

1. pip install 'pageindex[chat]' (or pip install openai-agents)
2. If you only need Anthropic models, use messages() instead — it runs on the anthropic extra
3. Pin openai-agents in requirements to avoid environment drift

Example fix

# before
pip install pageindex

# after
pip install 'pageindex[chat]'

try:
    import agents  # noqa
    HAS_AGENTS = True
except ImportError:
    HAS_AGENTS = False
if not HAS_AGENTS:
    raise RuntimeError('install pageindex[chat] or use messages()')

null

try:
    client.chat_completions(...)
except PageIndexAPIError as e:
    if 'pip install openai-agents' in str(e):
        # fall back to messages() or install and retry
        ...

When it happens

Trigger: Installing only the base pageindex package (no chat extras) then calling client.chat_completions(model=..., ...) or client.responses(...).

Common situations: Minimal install in CI, slim Docker images, upgrading and losing the extras, assuming the SDK is a transitive dependency.

Related errors

• doc_id must be a string or a list of strings.
• system message content must be a string or a list of text pa
• messages must be a non-empty list.
• Each message must be a dict with 'role' and 'content'.
• chat_completions content must be a string; for structured it

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