> ## Documentation Index
> Fetch the complete documentation index at: https://developers.agentx.so/llms.txt
> Use this file to discover all available pages before exploring further.

# LlamaIndex

> Auto-trace query engines, chat engines, and agents with AgentXLlamaIndexHandler

Install the integration extra:

```bash theme={null}
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.

```python theme={null}
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`:

```python theme={null}
query_engine = index.as_query_engine(callback_manager=CallbackManager([handler]))
```

<Note>
  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.
</Note>

## 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`                                                                                                                          |

<Note>
  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.
</Note>

## `AgentXLlamaIndexHandler` reference

```python theme={null}
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          |

<Note>
  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.
</Note>