# Lens

```json metadata
{
  "schema_version": 2,
  "title": "Lens",
  "description": "Debug AI agent answers by tracing the context behind each turn, from retrieval to prompt.",
  "categories": ["docs","develop","ai"],
  "tableOfContents": {"sections":[{"id":"what-is-lens","title":"What is Lens?"},{"id":"why-use-lens","title":"Why use Lens?"},{"id":"concepts","title":"Concepts"},{"id":"quick-example","title":"Quick example"},{"id":"use-lens","title":"Use Lens"}]}

,
  "codeExamples": [{"codetabsId":"iris_lens_quickstart-steptrace_turn","difficulty":"beginner","id":"trace_turn","languages":[{"clientId":"iris-python","clientName":"Python (Iris)","id":"Python (Iris)","langId":"python","panelId":"panel_Python (Iris)_iris_lens_quickstart-steptrace_turn"}]}]
}
```

## Code examples

These examples connect to Iris services using SDKs or HTTP requests with curl. Follow one language throughout each walkthrough.


## What is Lens?

Lens is a Redis Iris observability tool that traces your AI agent's turns. A turn is one agent exchange, such as answering a single message. For each turn, Lens records what each source returned, such as a memory recall or a retrieval, and what entered the prompt. It also records which model and tool calls ran, how long each step took, and how the turn ended.

When your agent gives a wrong answer, Lens shows where it went wrong. For example, you might see that the right memory was recalled but dropped from the prompt, or that a retrieval came back empty.

<div class="grid grid-cols-1 md:grid-cols-3 gap-6 my-8">
  
  
  
</div>

## Why use Lens?

- **See why an agent answered the way it did:** Compare what each source returned with what entered the prompt, turn by turn.
- **Iris services trace themselves:** Agent Memory, Agent Playbooks, and Context Gateway calls appear in the turn with no extra code.
- **Model calls traced automatically:** Calls through OpenAI, Anthropic, Amazon Bedrock, and LangChain clients appear with their prompts, completions, and token counts.
- **Built on OpenTelemetry:** Lens joins the tracer your application already uses, and Iris service steps reach your existing observability tools as well.
- **You control content capture:** Capture prompts and retrieved text for debugging, or keep only IDs, hashes, and counts.
- **Background export:** Lens exports in the background, so your agent never waits for it. If an export fails, the error stays out of your agent's code.

## Concepts

Lens groups turns into sessions by agent, and records each turn's steps. See [Lens concepts](https://redis.io/docs/latest/develop/ai/context-engine/lens/concepts).

1. Your agent opens a turn for each message with the Redis Iris software development kit (SDK).
1. The SDK records each step in the turn: retrievals, memory recalls, prompt assembly, model calls, tool calls, and Iris service calls.
1. Lens assembles the turn and groups it into sessions by agent.
1. You inspect the turn in the Lens user interface (UI) or query it with the read application programming interface (API).

![Your agent sends its turns to Lens through the Redis Iris SDK, and the Iris services it calls record their own steps in the same turn. You inspect sessions in the Lens UI or query turns with the read API.](https://redis.io/docs/latest/images/ai/context-engine/lens-how-it-works.svg)

## Quick example

1. Set up a Lens instance and get its endpoints and keys:
    - **Redis Cloud:** [Create Lens](https://redis.io/docs/latest/operate/iris/lens/create-lens).
    - **Self-managed:** [Deploy Lens on Kubernetes](https://redis.io/docs/latest/operate/iris/lens/self-managed).
1. Install the Redis Iris Python package:

    ```bash
    pip install 'redis-iris[llm-tracing]>=1.0.0'
    ```

1. With `IRIS_LENS_ENDPOINT`, `IRIS_LENS_API_KEY`, and `IRIS_LENS_AGENT_ID` in your environment, trace a turn. The example calls OpenAI; use any supported client.

**Available in:** Python (Iris)

##### Python (Iris)

```python
import uuid

from openai import OpenAI
from redis_iris import lens

lens.init()
client = OpenAI()

session_id = f"quickstart-{uuid.uuid4().hex[:8]}"

with lens.turn(session_id, user_id="user-1042") as turn:
    response = client.responses.create(
        model="gpt-4.1-mini",
        input="Where can I see my refund status?",
    )
    print(response.output_text)
    turn.set_outcome("completed")

turn_id = turn.trace_id
print(f"Session: {session_id}")
print(f"Turn: {turn_id}")
```



Follow the [quickstart](https://redis.io/docs/latest/develop/ai/context-engine/lens/quickstart) to read the turn back.

## Use Lens

- [Instrument an agent](https://redis.io/docs/latest/develop/ai/context-engine/lens/instrument): record turns, retrievals, prompt assembly, and custom steps.
- [Integrate with an agent framework](https://redis.io/docs/latest/develop/ai/context-engine/lens/agent-integration): trace LangGraph, OpenAI Agents SDK, Google Agent Development Kit (ADK), and your own loop.
- [Inspect sessions](https://redis.io/docs/latest/develop/ai/context-engine/lens/inspect-sessions): find a session and read its turns in the Lens UI.
- [Configure Lens](https://redis.io/docs/latest/develop/ai/context-engine/lens/configure): settings, keys, content capture, and OpenTelemetry.
- [Query sessions and turns](https://redis.io/docs/latest/develop/ai/context-engine/lens/read-api): read turns from code.
- [Limits and errors](https://redis.io/docs/latest/develop/ai/context-engine/lens/limits): request limits, export behavior, and troubleshooting.
- [API reference](https://redis.io/docs/latest/develop/ai/context-engine/lens/api-reference): the read API operations and data models.