Skip to content
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_id in 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.

EventSpan kindNotes
QueryStartEventchainTop-level query is pushed through pre-execution enforcement.
LLMChatStartEvent / LLMCompletionStartEventllmCaptures model + messages.
RetrievalStartEvent / EmbeddingStartEventretrieverRecords a RAG lookup or embedding call.
AgentToolCallEventtoolEvery tool call enforces with the tool name added to the allowlist check.
AgentRunStepStartEvent / AgentChatWithStepStartEventagentRecords a planning step from a LlamaIndex agent runner.
*EndEventCloses 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

What's next

LlamaIndex integration — Execlave Docs