{"record":{"id":"8d8a5b740eb8d306","repo":"run-llama/llama_index","slug":"agentopshandler-is-not-installed-please-install-i","errorCode":null,"errorMessage":"AgentOpsHandler is not installed. Please install it using `pip install llama-index-instrumentation-agentops`","messagePattern":"AgentOpsHandler is not installed\\. Please install it using `pip install llama-index-instrumentation-agentops`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/callbacks/global_handlers.py","lineNumber":119,"sourceCode":"        handler = argilla_callback_handler(**eval_params)\n    elif eval_mode == \"langfuse\":\n        try:\n            from llama_index.callbacks.langfuse import (\n                langfuse_callback_handler,\n            )  # pants: no-infer-dep\n        except ImportError:\n            raise ImportError(\n                \"LangfuseCallbackHandler is not installed. \"\n                \"Please install it using `pip install llama-index-callbacks-langfuse`\"\n            )\n        handler = langfuse_callback_handler(**eval_params)\n    elif eval_mode == \"agentops\":\n        try:\n            from llama_index.callbacks.agentops import (\n                AgentOpsHandler,\n            )  # pants: no-infer-dep\n        except ImportError:\n            raise ImportError(\n                \"AgentOpsHandler is not installed. \"\n                \"Please install it using `pip install llama-index-instrumentation-agentops`\"\n            )\n        AgentOpsHandler.init(**eval_params)\n    elif eval_mode == \"literalai\":\n        try:\n            from llama_index.callbacks.literalai import (\n                literalai_callback_handler,\n            )  # pants: no-infer-dep\n        except ImportError:\n            raise ImportError(\n                \"Literal AI Handler is not installed. \"\n                \"Please install it using `pip install llama-index-callbacks-literalai`\"\n            )\n        handler = literalai_callback_handler(**eval_params)\n    elif eval_mode == \"opik\":\n        try:\n            from llama_index.callbacks.opik import (","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/callbacks/global_handlers.py#L101-L137","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nset_global_handler('agentops')  # ImportError\n\n# after\n# pip install llama-index-instrumentation-agentops\nset_global_handler('agentops')","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec('llama_index.callbacks.agentops') is None:\n    raise SystemExit('pip install llama-index-instrumentation-agentops')","typeGuard":null,"tryCatchPattern":"try:\n    create_global_handler('agentops')\nexcept ImportError as e:\n    handler = None","preventionTips":["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"],"tags":["llama-index","callbacks","import-error","optional-dependency","agentops"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}