{
  "schema_version": 2,
  "id": "develop/ai/context-engine/lens/concepts",
  "title": "Lens concepts",
  "url": "https://redis.io/docs/latest/develop/ai/context-engine/lens/concepts/",
  "summary": "Understand sessions, turns, steps, outcomes, agents, content capture, and retention in Lens.",
  "tags": [
    "docs",
    "develop",
    "ai"
  ],
  "last_updated": "2026-11-03T16:48:30-08:00",
  "page_type": "content",
  "content_hash": "01addc1132dd74c2565a45fc81686eff989c34eeaea925db9e64846d90a449f0",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "These concepts explain what Lens records for each turn and how it organizes turns into sessions."
    },
    {
      "id": "sessions-threads-and-turns",
      "title": "Sessions, threads, and turns",
      "role": "content",
      "text": "A **turn** is one agent exchange: a user message in, an answer out. Lens records each turn as one OpenTelemetry trace, the standard record of one request and every operation it ran. The trace ID is the turn ID.\n\nA **session** groups the turns of one conversation. A **thread** is a sequence of turns within a session. You choose the session and thread IDs and pass them when you open a turn. When you omit the thread ID, Lens uses the session ID.\n\nUse opaque values, such as internal IDs or hashes, for session, thread, user, and agent IDs."
    },
    {
      "id": "what-a-turn-records",
      "title": "What a turn records",
      "role": "content",
      "text": "Each operation in a turn is a **step**. A turn can include these steps:\n\n| Step | What Lens records |\n| ---- | ----------------- |\n| Retrieval | The query, the data source, and each result's ID, score, and text. |\n| Memory recall | A retrieval from long-term memory, with the same details. |\n| Model call | The prompt, the completion, and token counts. |\n| Tool call | The tool, its input, its result, and how long it took. |\n| Iris service call | Agent Memory, Agent Playbooks, and Context Gateway calls. These services record their own steps. |\n| Custom step | Any operation you wrap yourself. |\n\nEvery step records its timing and whether it succeeded. See [Instrument an agent](https://redis.io/docs/latest/develop/ai/context-engine/lens/instrument) to record each kind of step."
    },
    {
      "id": "turn-outcomes",
      "title": "Turn outcomes",
      "role": "content",
      "text": "Set an outcome on each turn to record how it ended. You can then [filter sessions by outcome](https://redis.io/docs/latest/develop/ai/context-engine/lens/read-api#list-sessions) with the read application programming interface (API).\n\n| Outcome | Use it when |\n| ------- | ----------- |\n| `completed` | The agent finished its answer. |\n| `failed` | An error stopped the turn. |\n| `abandoned` | The user left before the turn finished. |\n| `refused` | The agent declined the request. |\n| `timeout` | The turn ran out of time. |\n\nA turn without an outcome still appears in Lens. Set the outcome on every path, including errors, so each turn is filterable."
    },
    {
      "id": "agents",
      "title": "Agents",
      "role": "content",
      "text": "Every turn carries an **agent ID**. Set it once per process with `IRIS_LENS_AGENT_ID` or `lens.init()`, or per turn with `lens.turn(agent_id=...)`. One Lens instance holds the sessions of all your agents, and you choose an agent to view its sessions."
    },
    {
      "id": "content-capture",
      "title": "Content capture",
      "role": "content",
      "text": "Lens captures content by default: prompts, completions, queries, retrieved text, memory text, frequently asked question (FAQ) answers, skill text, and tool inputs and results.\n\nYou can turn content capture off. Lens then keeps each step's IDs, content hashes, counts, sizes, timing, and outcome. See [Control content capture](https://redis.io/docs/latest/develop/ai/context-engine/lens/configure#control-content-capture)."
    },
    {
      "id": "retention",
      "title": "Retention",
      "role": "content",
      "text": "Lens keeps turn structure, timing, scores, and outcomes for the full retention window. Captured text has a shorter window. Your administrator sets both windows. See [self-managed retention](https://redis.io/docs/latest/operate/iris/lens/self-managed/configuration#retention)."
    }
  ],
  "examples": []
}