LlamaIndex

Install the integration extra:

pip install "agentx-python[llamaindex]" llama-index-core

Usage

Register AgentXLlamaIndexHandler on LlamaIndex’s global Settings.callback_manager (or scope it to a single query engine / agent). Every subsequent top-level query() / chat() / retrieve() call - including its nested retrieval and LLM steps - is traced automatically.

from agentx import AgentX
from agentx.integrations.llamaindex import AgentXLlamaIndexHandler
from llama_index.core import Settings, VectorStoreIndex, Document
from llama_index.core.callbacks import CallbackManager
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding

agentx = AgentX.from_env()

handler = AgentXLlamaIndexHandler(
    tracer=agentx.tracer,
    name="support-rag-agent",
    metadata={"env": "production"},
)

Settings.llm = OpenAI(model="gpt-4o-mini")
Settings.embed_model = OpenAIEmbedding()
Settings.callback_manager = CallbackManager([handler])

index = VectorStoreIndex.from_documents([
    Document(text="To cancel your subscription, go to Account → Subscription → Cancel."),
    Document(text="We offer a 14-day free trial, no credit card required."),
])

query_engine = index.as_query_engine()
response = query_engine.query("How do I cancel my subscription?")
print(response)

agentx.tracer.flush(timeout=10)

To scope tracing to one query engine instead of every LlamaIndex call in the process, pass the callback manager directly instead of setting it on the global Settings:

query_engine = index.as_query_engine(callback_manager=CallbackManager([handler]))

Building the index itself (VectorStoreIndex.from_documents(...)) is not traced - only real query/chat/retrieve/agent-step calls produce a trace. Node parsing, chunking, and embedding events fired during index construction are intentionally not sent to AgentX.

What gets traced

Each top-level call produces one trace: a query()/chat() call, an agent step, or - if you call a retriever or LLM directly with no query engine wrapping it - that bare call itself.

Field	Source
`input`	The query string, or the first LLM call’s prompt for a bare `llm.complete()`/`chat()` call
`output`	The final `Response`/completion text
`latencyMs`	Wall-clock time from the top-level event’s start to its end
`model`	`EventPayload.MODEL_NAME` from the LLM event, when the LLM integration populates it
`performanceSummary`	One execution step per nested `LLM` event, one retrieval step per nested `RETRIEVE` event (with `query`, `doc_count`, and the retrieved text), one tool-call step per `FUNCTION_CALL` event
`error`	Exception message from any nested event’s `EventPayload.EXCEPTION`

LlamaIndex’s CallbackManager.start_trace(trace_id) reuses a fixed operation-name string ("query", "chat", …) rather than a unique id per call, so AgentXLlamaIndexHandler doesn’t key state on it - it walks the real event_id/parent_id chain instead, which stays correct under concurrent calls in the same process.

`AgentXLlamaIndexHandler` reference

AgentXLlamaIndexHandler(
    tracer: Tracer,
    name: str = "llamaindex-agent",
    metadata: dict | None = None,
    session_id: str | None = None,
)

Parameter	Description
`tracer`	`agentx.tracer` from your `AgentX` instance
`name`	Label shown in the AgentX UI for every trace sent by this handler
`metadata`	Static key-value metadata attached to every trace
`session_id`	Links traces from the same conversation thread in the UI

Call tracer.flush() before your process exits in scripts or one-shot jobs. In long-running servers it is not required: traces drain automatically in the background.

Tracing

Framework Integrations

Usage

What gets traced

`AgentXLlamaIndexHandler` reference

​Usage

​What gets traced

​AgentXLlamaIndexHandler reference

Usage

What gets traced

`AgentXLlamaIndexHandler` reference