← Back to home
§ INTEGRATION · LLAMAINDEX
LlamaIndex event handler
Register one dispatcher event handler at app start. Every query, retrieval, LLM call, and agent tool call is governed and traced.
§ 01
Prerequisites
- Execlave account with an active API key — Settings → API keys.
- A registered agent in Execlave. Use the agent's lowercase-kebab
agent_idin the handler. - LlamaIndex
llama-index-core >=0.11(Python).
§ 02
Install
The handler is behind an optional extra so the default SDK install does not pull LlamaIndex as a transitive dependency.
Python
pip install 'execlave-sdk[llamaindex]'§ 03
Instant setup with a copilot
Paste this prompt into your AI coding assistant. It will wire Execlave into your existing LlamaIndex bootstrap.
§ Copy prompt · paste into your AI coding assistant
You are adding Execlave (an AI agent governance platform) to an existing Python project that uses LlamaIndex. Do not rewrite existing indexes, retrievers, or query engines — only attach instrumentation. Rules you MUST follow:1. Install the correct extra: `pip install 'execlave-sdk[llamaindex]'`. Add it to requirements.txt / pyproject.toml.2. Read `EXECLAVE_API_KEY` from environment variables. Never hardcode keys. Add it to `.env.example`.3. Create exactly ONE Execlave client per process and reuse it: `exe = Execlave(api_key=os.environ["EXECLAVE_API_KEY"])`.4. Register the handler ONCE at app start, not per request: ``` from llama_index.core.instrumentation import get_dispatcher from execlave.integrations.llamaindex import ExeclaveLlamaIndexHandler handler = ExeclaveLlamaIndexHandler(exe, agent_id="<stable-kebab-id>") get_dispatcher().add_event_handler(handler) ```5. `agent_id` is a stable kebab-case string identifying this app in the Execlave dashboard.6. Wrap `query_engine.query()` / `agent.chat()` in try/except for `execlave.errors.PolicyBlockedError`. On block, return a structured 4xx response containing `exc.violations`. Do NOT swallow the error.7. Do NOT call `exe.enforce_policy` manually — the handler runs enforcement on `QueryStartEvent` and `AgentToolCallEvent`.8. On process shutdown (ASGI lifespan / SIGTERM handler), call `exe.flush()`. Deliverables:- One diff per file. Touch only app bootstrap and the entry-point that runs queries.- Add `EXECLAVE_API_KEY` and optional `EXECLAVE_BASE_URL` to `.env.example`. Reference: https://www.execlave.com/docs/integrations/llamaindexAPI reference: https://www.execlave.com/docs/sdk-reference§ 04
Quick start
One handler subscribes to every event LlamaIndex emits.
Python
from llama_index.core.instrumentation import get_dispatcherfrom execlave import Execlavefrom execlave.integrations.llamaindex import ExeclaveLlamaIndexHandler exe = Execlave(api_key="exe_prod_...")handler = ExeclaveLlamaIndexHandler(exe, agent_id="rag-bot") dispatcher = get_dispatcher()dispatcher.add_event_handler(handler)dispatcher.add_span_handler(handler.span_handler()) # Enforcement fires on QueryStartEvent (user query) and on every# AgentToolCallEvent (tool name + arguments). A PolicyBlockedError# halts the LlamaIndex pipeline before the tool or LLM is invoked.response = index.as_query_engine().query("Summarise our Q3 pipeline")§ 05
What gets instrumented
Every LlamaIndex dispatcher event maps to a span under the same trace id.
| Event | Span kind | Notes |
|---|---|---|
QueryStartEvent | chain | Top-level query is pushed through pre-execution enforcement. |
LLMChatStartEvent / LLMCompletionStartEvent | llm | Captures model + messages. |
RetrievalStartEvent / EmbeddingStartEvent | retriever | Records a RAG lookup or embedding call. |
AgentToolCallEvent | tool | Every tool call enforces with the tool name added to the allowlist check. |
AgentRunStepStartEvent / AgentChatWithStepStartEvent | agent | Records a planning step from a LlamaIndex agent runner. |
*EndEvent | — | Closes the matching span with output + token usage when present. |
§ 06
Handling blocks
Enforcement runs on the top-level query and on every tool call. A blocked call raises PolicyBlockedError with the exact violations list.
Python
from execlave.errors import PolicyBlockedError try: response = query_engine.query(user_question)except PolicyBlockedError as exc: # Policy blocked the query before the LLM was called. return {"error": "blocked", "violations": exc.violations}§ 07