{
  "schema_version": 2,
  "id": "develop/ai/context-engine/lens",
  "title": "Lens",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/",
  "summary": "Debug AI agent answers by tracing the context behind each turn, from retrieval to prompt.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-11-03T16:48:30-08:00",
  "children": [
    {
      "id": "develop/ai/context-engine/lens/concepts",
      "summary": "Understand sessions, turns, steps, outcomes, agents, content capture, and retention in Lens.",
      "title": "Lens concepts",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/concepts/"
    },
    {
      "id": "develop/ai/context-engine/lens/quickstart",
      "summary": "Trace one agent turn with the Redis Iris SDK, then find it in Lens and read it back with the read API.",
      "title": "Lens quickstart",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/quickstart/"
    },
    {
      "id": "develop/ai/context-engine/lens/instrument",
      "summary": "Record turns, retrievals, memory recalls, prompt assembly, model calls, and custom steps with the Redis Iris SDK.",
      "title": "Instrument an agent",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/instrument/"
    },
    {
      "id": "develop/ai/context-engine/lens/agent-integration",
      "summary": "Trace LangGraph, OpenAI Agents SDK, Google ADK, and your own agent loop with Lens, across Agent Memory, Agent Playbooks, and Context Gateway.",
      "title": "Integrate Lens with agent frameworks",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/agent-integration/"
    },
    {
      "id": "develop/ai/context-engine/lens/inspect-sessions",
      "summary": "Find a session in the Lens UI and read each turn's steps, timing, and captured content.",
      "title": "Inspect sessions",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/inspect-sessions/"
    },
    {
      "id": "develop/ai/context-engine/lens/configure",
      "summary": "Configure the Lens SDK settings, API keys, content capture, OpenTelemetry integration, and TLS.",
      "title": "Configure Lens",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/configure/"
    },
    {
      "id": "develop/ai/context-engine/lens/read-api",
      "summary": "List agents and sessions, and read turns and their captured content with the Lens read API.",
      "title": "Query sessions and turns",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/read-api/"
    },
    {
      "id": "develop/ai/context-engine/lens/limits",
      "summary": "Lens request limits, how the SDK exports turns, error responses, and troubleshooting.",
      "title": "Lens limits and errors",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/limits/"
    },
    {
      "id": "develop/ai/context-engine/lens/api-reference",
      "summary": "",
      "title": "Lens read API",
      "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/api-reference/"
    }
  ],
  "page_type": "content",
  "content_hash": "592e8ab9a762216a6b4750e2348ff778082134bea064dcecd07fd5400e51bce4",
  "sections": [
    {
      "id": "code-examples",
      "title": "Code examples",
      "role": "example",
      "text": "These examples connect to Iris services using SDKs or HTTP requests with curl. Follow one language throughout each walkthrough."
    },
    {
      "id": "what-is-lens",
      "title": "What is Lens?",
      "role": "content",
      "text": "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.\n\nWhen 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.\n\n<div class=\"grid grid-cols-1 md:grid-cols-3 gap-6 my-8\">\n  \n  \n  \n</div>"
    },
    {
      "id": "why-use-lens",
      "title": "Why use Lens?",
      "role": "content",
      "text": "- **See why an agent answered the way it did:** Compare what each source returned with what entered the prompt, turn by turn.\n- **Iris services trace themselves:** Agent Memory, Agent Playbooks, and Context Gateway calls appear in the turn with no extra code.\n- **Model calls traced automatically:** Calls through OpenAI, Anthropic, Amazon Bedrock, and LangChain clients appear with their prompts, completions, and token counts.\n- **Built on OpenTelemetry:** Lens joins the tracer your application already uses, and Iris service steps reach your existing observability tools as well.\n- **You control content capture:** Capture prompts and retrieved text for debugging, or keep only IDs, hashes, and counts.\n- **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."
    },
    {
      "id": "concepts",
      "title": "Concepts",
      "role": "content",
      "text": "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).\n\n1. Your agent opens a turn for each message with the Redis Iris software development kit (SDK).\n1. The SDK records each step in the turn: retrievals, memory recalls, prompt assembly, model calls, tool calls, and Iris service calls.\n1. Lens assembles the turn and groups it into sessions by agent.\n1. You inspect the turn in the Lens user interface (UI) or query it with the read application programming interface (API).\n\n![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)"
    },
    {
      "id": "quick-example",
      "title": "Quick example",
      "role": "content",
      "text": "1. Set up a Lens instance and get its endpoints and keys:\n    - **Redis Cloud:** [Create Lens](https://redis.io/docs/latest/operate/iris/lens/create-lens).\n    - **Self-managed:** [Deploy Lens on Kubernetes](https://redis.io/docs/latest/operate/iris/lens/self-managed).\n1. Install the Redis Iris Python package:\n\n    [code example]\n\n1. 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.\n\n**Available in:** Python (Iris)\n\n##### Python (Iris)\n\n[code example]\n\n\n\nFollow the [quickstart](https://redis.io/docs/latest/develop/ai/context-engine/lens/quickstart) to read the turn back."
    },
    {
      "id": "use-lens",
      "title": "Use Lens",
      "role": "content",
      "text": "- [Instrument an agent](https://redis.io/docs/latest/develop/ai/context-engine/lens/instrument): record turns, retrievals, prompt assembly, and custom steps.\n- [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.\n- [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.\n- [Configure Lens](https://redis.io/docs/latest/develop/ai/context-engine/lens/configure): settings, keys, content capture, and OpenTelemetry.\n- [Query sessions and turns](https://redis.io/docs/latest/develop/ai/context-engine/lens/read-api): read turns from code.\n- [Limits and errors](https://redis.io/docs/latest/develop/ai/context-engine/lens/limits): request limits, export behavior, and troubleshooting.\n- [API reference](https://redis.io/docs/latest/develop/ai/context-engine/lens/api-reference): the read API operations and data models."
    }
  ],
  "examples": [
    {
      "id": "quick-example-ex0",
      "language": "bash",
      "code": "pip install 'redis-iris[llm-tracing]>=1.0.0'",
      "section_id": "quick-example"
    },
    {
      "id": "quick-example-ex1",
      "language": "python",
      "code": "import uuid\n\nfrom openai import OpenAI\nfrom redis_iris import lens\n\nlens.init()\nclient = OpenAI()\n\nsession_id = f\"quickstart-{uuid.uuid4().hex[:8]}\"\n\nwith lens.turn(session_id, user_id=\"user-1042\") as turn:\n    response = client.responses.create(\n        model=\"gpt-4.1-mini\",\n        input=\"Where can I see my refund status?\",\n    )\n    print(response.output_text)\n    turn.set_outcome(\"completed\")\n\nturn_id = turn.trace_id\nprint(f\"Session: {session_id}\")\nprint(f\"Turn: {turn_id}\")",
      "section_id": "quick-example"
    }
  ]
}