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

# LlamaIndex

> Capture traces from LlamaIndex agents and workflows with OpenInference and OpenTelemetry

## Choose a setup method

| Method | Use it when |
| - | - |
| **Agnost AI skill** | You want your coding agent to inspect the app, make the change, and verify it. |
| **Agnost AI SDK** | You want explicit control over the interaction boundaries and fields. |
| **OpenTelemetry** | The framework already emits useful spans or you operate an OTel pipeline. |

Start with one method for a call path. Combining SDK tracking with framework
OpenTelemetry on the same call can create duplicate interactions.

## Recommended: Agnost AI skill

> [!NOTE]
>
> **Recommended.** Choose this path when you want your coding agent to inspect the
> project, select a supported transport, make the smallest instrumentation change,
> send a test event, and verify that it reached Agnost AI.

Install the skill once in your coding-agent environment:

```bash theme={null} theme={null} theme={null} theme={null} theme={null}
npx skills add AgnostAI/skills --skill agnost-ai
```

Run the framework-specific prompt below from the application root. Review the
resulting diff before deploying it.

```text theme={null}
Use the agnost-ai skill to add Agnost AI analytics to this LlamaIndex application.
Org ID: your-org-id
Instrument the real agent.run() path, set user and session IDs, and verify one fresh interaction.
```

## Manual setup: Agnost AI SDK

```bash theme={null}
pip install agnost
```

```python theme={null}
import agnost

agnost.init("your-org-id")
interaction = agnost.begin(
    user_id="u-42",
    agent_name="llamaindex-support",
    input=prompt,
    conversation_id="sess-123",  # groups turns into one conversation
)
if interaction is None:
    raise RuntimeError("Agnost is not initialized. Call agnost.init() first.")
try:
    response = await agent.run(prompt)
    interaction.end(output=str(response))
except Exception as exc:
    interaction.end(output=str(exc), success=False)
    raise
```

Call `agnost.shutdown()` once when the application exits, not after each request.

## Manual setup: OpenTelemetry

The [OpenInference LlamaIndex instrumentation](https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-llama-index) emits an OpenTelemetry span for every agent run, workflow step, model call, and tool call. Send those spans to Agnost AI over OTLP, and wrap each turn in one short span that carries the user's message and the agent's answer.

> [!NOTE]
>
> LlamaIndex also ships `llama-index-observability-otel`. Its spans carry raw workflow events with no model, message, or token attributes, so Agnost AI does not ingest them. Use OpenInference.

### 1. Install

```bash theme={null}
pip install llama-index openinference-instrumentation-llama-index opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

Tested with `llama-index` 0.14.25, `openinference-instrumentation-llama-index` 4.7.6, and `opentelemetry-sdk` 1.45.2 on Python 3.12.

### 2. Point OpenTelemetry at Agnost AI and run an agent

```python theme={null}
import asyncio
import json
import os

from openinference.instrumentation import using_attributes
from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

provider = TracerProvider(resource=Resource.create({"service.name": "my-llamaindex-agent"}))
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(
    endpoint="https://otel.agnost.ai/v1/traces",
    headers={"X-Agnost-Org-ID": os.environ["AGNOST_ORG_ID"]},
)))
LlamaIndexInstrumentor().instrument(tracer_provider=provider)
tracer = provider.get_tracer("agnost")


def get_order_status(order_id: str) -> str:
    """Look up the shipping status of an order."""
    return "shipped"


agent = FunctionAgent(
    name="support-agent",
    tools=[get_order_status],
    llm=OpenAI(
        model="gpt-4o-mini",
        # Ask OpenAI for token usage on streamed responses.
        additional_kwargs={"stream_options": {"include_usage": True}},
    ),
    system_prompt="You are a support agent for an online store.",
)


async def run_turn(message: str, user_id: str, session_id: str) -> str:
    """Run one agent turn and record it as one Agnost AI conversation turn."""
    with using_attributes(user_id=user_id, session_id=session_id):
        with tracer.start_as_current_span("agent_turn", attributes={
            "gen_ai.operation.name": "invoke_agent",
            "gen_ai.agent.name": agent.name,
            "user.id": user_id,
            "session.id": session_id,
            "gen_ai.input.messages": json.dumps(
                [{"role": "user", "parts": [{"type": "text", "content": message}]}]),
        }) as span:
            answer = str(await agent.run(message))
            span.set_attribute("gen_ai.output.messages", json.dumps(
                [{"role": "assistant", "parts": [{"type": "text", "content": answer}]}]))
            return answer


async def main():
    print(await run_turn("Where is my order A-1042?", user_id="user-42", session_id="session-abc"))


asyncio.run(main())
provider.shutdown()  # flush spans before a short script exits
```

What each piece does:

* **`LlamaIndexInstrumentor().instrument()`** traces agents, workflows, query engines, retrievers, LLMs, and tools.
* **`using_attributes(user_id=..., session_id=...)`** writes `user.id` and `session.id` onto every span LlamaIndex emits inside the block. Every turn with the same `session_id` lands in the same Agnost AI conversation.
* **The `agent_turn` span** becomes the root of each trace. Agnost AI builds the conversation transcript from each trace's root span, and the root span OpenInference writes for `agent.run()` holds the serialized workflow state, not the user's message. The wrapper puts the message and the final answer there instead. It only adds span attributes, so it does not change how the agent runs.

In a long-running server, create the `TracerProvider` and call `instrument()` once at startup, call `run_turn` per request, and call `provider.shutdown()` on graceful shutdown.

### What appears in Agnost AI

* **Conversations**: one per `session_id`. Agnost AI keeps the raw session ID as `original_conversation_id` in the conversation metadata.
* **Users**: the `user_id` you pass to `using_attributes`.
* **Messages**: the user's message and the agent's answer for each turn, from the `agent_turn` span.
* **Events**: the agent run, each workflow step (`chain`), each model call (`llm`), and each tool call (`tool`) in a nested tree. Model calls include the model name, input and output messages, tool calls, and token counts. Tool calls include the tool name, arguments, and result.

### Verify

Run the script, wait one to five minutes for ingestion, then open **Conversations** in Agnost AI. Confirm the conversation shows your `user_id`, a user message and an assistant answer, and a `get_order_status` tool event with arguments and a result.

### Troubleshooting

* **Nothing arrives**: confirm the exporter's headers contain `X-Agnost-Org-ID`, and that the script calls `provider.shutdown()` or `provider.force_flush()` before it exits. `BatchSpanProcessor` exports in the background.
* **The user message is a large JSON blob of workflow state**: the turn ran outside the `agent_turn` span. Call `agent.run()` inside `run_turn`.
* **User or conversation is missing**: await `agent.run()` inside the `using_attributes` block.
* **Model calls have no token counts**: OpenAI returns usage on streamed responses only when asked. Keep `stream_options={"include_usage": True}` in `additional_kwargs`, or set `streaming=False` on the agent.

### References

* [OpenInference LlamaIndex instrumentation](https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-llama-index)
* [OpenInference context attributes](https://github.com/Arize-ai/openinference/tree/main/python/openinference-instrumentation)
* [LlamaIndex observability](https://developers.llamaindex.ai/python/framework/module_guides/observability/)

## Next steps

* [Conversations](https://docs.agnost.ai/using-conversations.md): review the complete LlamaIndex session.
* [Events](https://docs.agnost.ai/using-events.md): inspect agent, model, and tool activity.
* [Intents](https://docs.agnost.ai/using-intents.md): organize production conversations by what users wanted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.