---
title: "LlamaIndex"
url: "/docs/proxy/lens/integrations/llamaindex"
canonical_url: "https://docs.litellm.ai/docs/proxy/lens/integrations/llamaindex"
type: "docs"
last_updated: "2026-10-13"
summary: "Run LlamaIndex examples and send their agent traces to LiteLLM Lens."
related:
  - "/docs/proxy/lens/integrations/pydantic-ai"
  - "/docs/proxy/lens/integrations/google-adk"
---
# LlamaIndex

> Index of all LiteLLM docs: https://docs.litellm.ai/llms.txt

<!-- Generated from BerriAI/litellm-lens-example/llamaindex/README.md at a2294277609202247b71c08d7b491f5212809988. Edit the source README. -->

# LlamaIndex

For optional help from your coding agent, use [Set it up for me](https://github.com/BerriAI/lens/blob/main/docs/setup-with-agent.md#connect-an-agent-to-lens-already-running). It preserves your model connection and verifies a real trace after setup

Send LlamaIndex traces to [LiteLLM Lens](/docs/proxy/lens) using the runnable examples in this repository.

## Prerequisites

You need [Lens installed alongside LiteLLM](/docs/proxy/lens/deployment#configure-an-existing-proxy), a key with model access, and a configured model alias. The swarm example needs a model that supports tool calls. In **Lens > Traces > Set up tracing**, click **Generate tracing key** and copy the **Traces endpoint** under **Connection details**. Ask your administrator for these if you cannot create a tracing key.

Install [uv](https://docs.astral.sh/uv/getting-started/installation/). It uses the checked-in Python version and resolves each example’s dependencies from its uv workspace.

## Configuration

For a fresh checkout:

```bash
git clone https://github.com/BerriAI/litellm-lens-example.git
cd litellm-lens-example/llamaindex
cp .env.example .env
```

If you already cloned the repository, run the remaining commands from `llamaindex/`. Copy [.env.example](https://github.com/BerriAI/litellm-lens-example/blob/a2294277609202247b71c08d7b491f5212809988/llamaindex/.env.example) to `.env` if it does not exist, then set:

| Variable              | Value                                                                                                                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LITELLM_GATEWAY_URL` | Your gateway’s base URL without a trailing slash or `/v1`, for example `http://localhost:4002`                                                                                                    |
| `LITELLM_API_KEY`     | Your LiteLLM model key                                                                                                                                                                            |
| `LENS_URL`            | Copy **Traces endpoint** from Lens tracing setup and remove the final `/v1/traces`. Keep `/lens-ingest` if present. For example, `http://localhost:4318` or `https://gateway.example/lens-ingest` |
| `LENS_TRACING_KEY`    | The dedicated tracing key from Lens tracing setup                                                                                                                                                 |
| `LITELLM_MODEL`       | A model alias configured on your gateway                                                                                                                                                          |

The checked-in values target a local development gateway. Replace them for your deployment. Keep the exporter settings from `.env.example`; the examples configure their trace exporters in code. They send traces to `LENS_URL/v1/traces` with the tracing key as a bearer token.

Leave `MOCK_LITELLM_GATEWAY_URL` unset unless you intend to send an additional trace copy to the local [recorder](https://github.com/BerriAI/litellm-lens-example/blob/a2294277609202247b71c08d7b491f5212809988/recorder/AGENTS.md).

## Run an example

### Simple agent

A `FunctionAgent` answers one question.

```bash
uv run --env-file .env --package lens-llamaindex-simple simple/main.py
```

See [simple/main.py](https://github.com/BerriAI/litellm-lens-example/blob/a2294277609202247b71c08d7b491f5212809988/llamaindex/simple/main.py) for the implementation.

### Agent swarm

An `AgentWorkflow` hands off from `research_agent` to `search_agent`, then `writer_agent`.

```bash
uv run --env-file .env --package lens-llamaindex-swarm swarm/main.py
```

See [swarm/main.py](https://github.com/BerriAI/litellm-lens-example/blob/a2294277609202247b71c08d7b491f5212809988/llamaindex/swarm/main.py) for the implementation.

## Verify the trace

After the example prints its answer, open **Lens > Traces** on your gateway and select the new run. Look for the run associated with `research_agent`. Inspect the input, output, and model spans. For the swarm, inspect the specialist activity described above; its exact span layout depends on the framework.

## How tracing works

The LlamaIndex instrumentor is enabled before importing the framework. The examples label the process as research\_agent and disable framework streaming; specialist names appear in workflow and handoff data.

## Troubleshooting

If model calls fail, check the gateway URL, key, and model alias. If an answer appears but the trace is missing, check the terminal for exporter errors and confirm the Lens ingestion service is reachable with your tracing key. A model call succeeding does not confirm that its trace export succeeded.

Multiple model-related spans can represent one model call. Specialist names and model-call spend depend on the attributes exported by the framework and how the gateway normalizes them.

## Related pages

- [Pydantic AI](https://docs.litellm.ai/docs/proxy/lens/integrations/pydantic-ai.md)
- [Google ADK](https://docs.litellm.ai/docs/proxy/lens/integrations/google-adk.md)