run-llama/llama_index · error · ImportError

AgentOpsHandler is not installed. Please install it using `p

Error message

AgentOpsHandler is not installed. Please install it using `pip install llama-index-instrumentation-agentops`

What it means

Raised by create_global_handler() when eval_mode is 'agentops' but the AgentOps integration package is missing. Note the package name differs from the others: it is llama-index-instrumentation-agentops, not llama-index-callbacks-agentops, because AgentOps uses the newer instrumentation API. The lazy import of AgentOpsHandler fails and is re-raised with this message.

Source

Thrown at llama-index-core/llama_index/core/callbacks/global_handlers.py:119

        handler = argilla_callback_handler(**eval_params)
    elif eval_mode == "langfuse":
        try:
            from llama_index.callbacks.langfuse import (
                langfuse_callback_handler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "LangfuseCallbackHandler is not installed. "
                "Please install it using `pip install llama-index-callbacks-langfuse`"
            )
        handler = langfuse_callback_handler(**eval_params)
    elif eval_mode == "agentops":
        try:
            from llama_index.callbacks.agentops import (
                AgentOpsHandler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "AgentOpsHandler is not installed. "
                "Please install it using `pip install llama-index-instrumentation-agentops`"
            )
        AgentOpsHandler.init(**eval_params)
    elif eval_mode == "literalai":
        try:
            from llama_index.callbacks.literalai import (
                literalai_callback_handler,
            )  # pants: no-infer-dep
        except ImportError:
            raise ImportError(
                "Literal AI Handler is not installed. "
                "Please install it using `pip install llama-index-callbacks-literalai`"
            )
        handler = literalai_callback_handler(**eval_params)
    elif eval_mode == "opik":
        try:
            from llama_index.callbacks.opik import (

View on GitHub (pinned to afd0fef371)

Solutions

pip install llama-index-instrumentation-agentops
Verify: python -c "from llama_index.callbacks.agentops import AgentOpsHandler"
Set the AGENTOPS_API_KEY environment variable before init
Remove the agentops eval mode if session tracing is not wanted

Example fix

# before
set_global_handler('agentops')  # ImportError

# after
# pip install llama-index-instrumentation-agentops
set_global_handler('agentops')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('llama_index.callbacks.agentops') is None:
    raise SystemExit('pip install llama-index-instrumentation-agentops')

Try / catch

try:
    create_global_handler('agentops')
except ImportError as e:
    handler = None

Prevention

This package breaks the naming convention: instrumentation-*, not callbacks-* — double-check the pip name
Automate a find_spec check per enabled eval mode at app startup

When it happens

Trigger: create_global_handler('agentops', ...) or set_global_handler('agentops') without the wheel; `from llama_index.callbacks.agentops import AgentOpsHandler` raises ImportError. Installing llama-index-callbacks-agentops (which does not exist) or plain agentops is not enough.

Common situations: Assuming the naming convention of the other callback extras and installing the wrong (or no) package; using AgentOps session tracing in a container built from a core-only dependency spec.

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/8d8a5b740eb8d306. Report an issue: GitHub.