LlamaIndex Integration
Register ZespanLlamaIndexHandler with Settings.callbackManager once and every LLM call, tool use, vector retrieval, and agent step is traced automatically.
LlamaIndex is a Python and TypeScript framework for building RAG applications — query engines, retrievers, agents, and data pipelines — over structured and unstructured data.
Getting Started
Install the SDK
Install @zespan/sdk alongside llamaindex.
npm install @zespan/sdk llamaindexRegister ZespanLlamaIndexHandler
Add ZespanLlamaIndexHandler to Settings.callbackManager before creating your index or query engine. All subsequent LlamaIndex calls are traced automatically.
import { Settings } from 'llamaindex';
import { Zespan, ZespanLlamaIndexHandler } from '@zespan/sdk';
Zespan.init({ apiKey: process.env.ZESPAN_API_KEY });
Settings.callbackManager.addEventHandler(
new ZespanLlamaIndexHandler()
);
// Your existing code unchanged
const queryEngine = index.asQueryEngine();
const response = await queryEngine.query({ query: 'What is RAG?' });View traces in Zespan
Open Trace Explorer. Each query appears as a trace with the full RAG pipeline — retrieval, reranking, and synthesis — as nested spans.
What's captured automatically
- Full RAG pipeline: query encoding, retrieval, reranking, and synthesis as linked spans
- Retrieved documents: scores, node counts, and chunk content per retrieval span
- Synthesis LLM cost: token usage attributed to the synthesis call separately from retrieval
- Works with query engines, agents, and tools
- LlamaIndex ReAct agents: tool invocations and reasoning steps as child spans
- Python: ZespanLlamaIndexCallbackHandler registered via Settings for Python LlamaIndex
FAQ
Do I need to modify my index or query engine?
No. Register ZespanLlamaIndexHandler once with Settings.callbackManager. All LlamaIndex pipelines in that process are traced automatically.
Does this work for Python LlamaIndex?
Yes. Use ZespanLlamaIndexCallbackHandler from the Zespan Python SDK and register it via LlamaIndex's Settings in the same way.
Start free — 10K traces a month, no card needed
LlamaIndex integration works on all plans including the free tier.