MOD-20119: Lens developer docs by therealaditigupta · Pull Request #4329 · redis/docs

therealaditigupta · 2026-10-23T01:29:02Z

MOD-20119: customer-facing developer documentation for Lens, the Redis Iris observability product for AI agents.

Draft. It will be marked ready for review when publication is approved.

In this PR

content/develop/ai/context-engine/lens/: ten pages: landing page, concepts, quickstart, instrument an agent, agent integration, inspect sessions, configure, read API, limits and errors, and the API reference.
content/develop/ai/context-engine/lens/api-reference/openapi.json: the published read API contract, copied unchanged from iris-sdks openapi-lens.json.
local_examples/iris/lens/: eleven example sets, rendered as Python (Iris) and cURL (Iris) tabs.
static/images/ai/context-engine/lens-how-it-works.svg, lens-turn.svg: two diagrams.
content/develop/ai/context-engine/_index.md: a Lens tile.
content/develop/ai/context-engine/lens/AGENTS.md: Lens terminology, disclosure, and framing rules for AI-assisted editing (not published).
for-ais-only/lens-docs-design.md: the section design and remaining work (not published).

Verification

Every SDK call and response field used in the examples was checked against the published redis-iris 0.1.0a6 and redis-agent-lens 0.1.0a2 packages.
Instrumentation examples were run against a local ingest stand-in. Model calls and Iris product services were stubbed, and each example exported the expected steps under one turn.
Read API examples (Python and cURL) were run against a fake read API covering all six operations, including pagination.
All example sets parse with the repo's example processor, every clients-example reference resolves, and every internal link and anchor resolves.
An independent accuracy review against the service, SDK, and UI source and an independent reader review were applied.
Not yet run against a live Lens instance, and the site build hasn't been run locally.

Open items

Operator handoffs are marked with TODO comments until the operator docs (MOD-18980) land.
The published read API contract contains some internal wording in field descriptions; to be fixed at the source.

🤖 Generated with Claude Code

Note

Low Risk
Documentation and static assets only; no application runtime, auth, or data-path code changes.

Overview
Adds customer-facing developer documentation for Lens (Redis Iris agent observability) under content/develop/ai/context-engine/lens/, and surfaces it from the context engine index with a new Lens tile.

The new section covers tracing and debugging agent turns end to end: concepts, quickstart, instrumentation (redis_iris.lens), framework integration (LangGraph, OpenAI Agents SDK, Google ADK, custom loops), UI inspection, configuration, read API usage (redis-agent-lens), limits/errors, and a generated read API reference backed by a copied OpenAPI contract. Two SVG diagrams illustrate how tracing flows and what a turn records.

Runnable tabbed examples live in local_examples/iris/lens/ (eleven sets, Python and cURL) and are wired into pages via clients-example. Editor-only assets include lens/AGENTS.md, CLAUDE.md, and for-ais-only/lens-docs-design.md; operator handoffs are left as TODO comments until operator docs exist.

^{Reviewed by Cursor Bugbot for commit bb5e133. Bugbot is set up for automated code reviews on this repo. Configure here.}

Plan the customer-facing Lens developer docs under content/develop/ai/context-engine/lens/: decisions, sources, the page-by-page structure, example sets, validation, reviewers, and remaining work. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…n in the Lens docs design Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Add the Lens conventions file, the concepts page, the quickstart, and its Python example. The example's export and read steps were checked against a local ingest sink and a fake read API; a live-instance run is still to do. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Move the quickstart example under local_examples/iris/ so it renders as Python (Iris), and add a cURL (Iris) source for reading the turn back. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CLAassistant · 2026-10-23T01:29:11Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

github-actions · 2026-10-23T01:29:17Z

github-actions · 2026-10-23T01:29:21Z

🧠 Redis Memory

Found 9 related items from repository history (1 new this commit):

PR — WIP: Playbook developer docs

Adds the Agent Playbooks developer docs under /develop/ai/context-engine/agent-playbook/ for docs-team and product review. The guides cove
PR — Iris concepts

Add four new concepts documents for Iris, RAM, Langcache and CR.
PR — RED-220418: Add Context Gateway developer docs

Summary
PR — WIP: Redis Agent Playbooks developer docs

MOD-19391 — Redis Agent Playbooks developer documentation.
PR — Add a dedicated Redis Iris docs space with its own nav and dark theme
- Header: replace the "AI agent builder" button with "Redis Iris", linking to the Iris landing page (desktop and mobile menus).
Commit — MOD-20119: Use the Iris example tabs for the Lens quickstart

MOD-20119: Use the Iris example tabs for the Lens quickstart
PR — Restyle Iris/AI context-engine tiles and update self-managed messaging
- Add a tile-card shortcode matching the integrate page's card style (colored swatch, uppercase mono label, description, "Learn more" link)
Commit — Rework Iris concepts pages for newcomer audiences and Google style

Rework Iris concepts pages for newcomer audiences and Google style
Commit — MOD-20119: Apply accuracy and reader review fixes to the Lens docs 🆕

MOD-20119: Apply accuracy and reader review fixes to the Lens docs

Memory updated at bb5e133

Add the Lens landing page, instrument, agent integration, inspect sessions, configure, read API, limits, and API reference pages; their example sets; two diagrams; and the Lens tile on the context engine index. Examples were checked against a local ingest stand-in or a fake read API, with model and Iris product calls stubbed; no live-instance run yet. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Accuracy: the attach example now reaches its write-back (END edge), the quickstart names the UI's real step labels, a turn needs an agent ID, init() and shutdown() return values are described as they behave, strict mode only covers session IDs, include() is only for spans outside a turn or dropped scopes, UI search covers loaded sessions, read example guards empty results, and the ingest error table matches the SDK's warnings. Reader: lead the landing page with what Lens shows, move the cross-product example first, make init() usage explicit, add missing-step troubleshooting and how to see SDK warnings, remove duplicated text, and expand acronyms at first use. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

mich-elle-luna

thank you!

mich-elle-luna

Hi Aditi,
Thank you for this draft, it is looking good. Here are some suggestions to improve clarity in a couple of areas.

mich-elle-luna · 2026-10-23T19:47:44Z

+- **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 product 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:** Your agent doesn't wait on Lens, and a failed export doesn't raise into your agent.


Suggested change

- **Background export:** Your agent doesn't wait on Lens, and a failed export doesn't raise into your agent.

- **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.

mich-elle-luna · 2026-10-23T19:53:35Z

+weight: 20
+---
+
+Open one Lens turn around each agent run, and the steps inside it join the turn. These examples need the Lens connection values from the [quickstart](/content/develop/ai/context-engine/lens/quickstart.md#configure-the-sdk). The framework examples also need a model provider key, such as `OPENAI_API_KEY`.


Suggested change

Open one Lens turn around each agent run, and the steps inside it join the turn. These examples need the Lens connection values from the [quickstart](/content/develop/ai/context-engine/lens/quickstart.md#configure-the-sdk). The framework examples also need a model provider key, such as `OPENAI_API_KEY`.

To trace an agent run in Lens, open a turn around it. Each step the agent takes inside the run, such as a memory recall or a model call, is recorded in that turn. For more about turns and steps, see [Lens concepts](/content/develop/ai/context-engine/lens/concepts.md).

Before you start, get the Lens connection values from the [quickstart](/content/develop/ai/context-engine/lens/quickstart.md#configure-the-sdk). The framework examples also need a model provider key, such as `OPENAI_API_KEY`.

mich-elle-luna · 2026-10-23T19:55:30Z

+
+## Trace one turn across Iris products
+
+When your agent uses Agent Memory, Agent Playbooks, and Context Gateway, one Lens turn shows how each shaped the answer. This example needs the connection values for each Iris product.


Suggested change

When your agent uses Agent Memory, Agent Playbooks, and Context Gateway, one Lens turn shows how each shaped the answer. This example needs the connection values for each Iris product.

When your agent uses Agent Memory, Agent Playbooks, and Context Gateway, a single Lens turn shows how each Iris product contributed to the agent's response. This example needs the connection values for each Iris product.

mich-elle-luna · 2026-10-23T19:58:31Z

+
+`workflows.turn()` runs each product's context step before the model and its write-back after. Every product call joins the turn:
+
+{{< clients-example set="iris_lens_iris_products" step="iris_products_turn" description="" lang_filter="Python (Iris)" footer="hide" />}}


ah I see why you are using 'products', we are calling these services in the rest of the docs, so maybe if we define the term 'products' it will be more clear.

mich-elle-luna · 2026-10-23T20:01:12Z

+
+Wrap the handler for one message in `lens.turn()`, and set the outcome on each path:
+
+{{< clients-example set="iris_lens_own_loop" step="own_loop_turn" description="" lang_filter="Python (Iris)" footer="hide" />}}


Probably should add a line after this example describing what it does. Also probably add a section here with links to next steps?

mich-elle-luna · 2026-10-23T20:04:07Z

+- docs
+- develop
+- ai
+description: Debug agent answers by tracing the context behind each turn, from retrieval to prompt.


Suggested change

description: Debug agent answers by tracing the context behind each turn, from retrieval to prompt.

description: Debug AI agent answers by tracing the context behind each turn, from retrieval to prompt.

mich-elle-luna · 2026-10-23T20:08:02Z

+
+## What is Lens?
+
+Lens shows why your AI agent answered the way it did. For each turn, it records what each source returned, what entered the prompt, which model and tool calls ran, how long each step took, and how the turn ended.


Suggested change

Lens shows why your AI agent answered the way it did. For each turn, it records what each source returned, what entered the prompt, which model and tool calls ran, how long each step took, and how the turn ended.

## 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.

therealaditigupta and others added 6 commits October 22, 2026 18:25

MOD-20119: Remove the reviewers table from the Lens docs design

e5c947f

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

MOD-20119: Remove review and approval steps from the Lens docs design

8546bce

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

MOD-20119: Settle deployments, banner, read API inputs, and validatio…

29a1d6a

…n in the Lens docs design Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

MOD-20119: Use the Iris example tabs for the Lens quickstart

95dd9f4

Move the quickstart example under local_examples/iris/ so it renders as Python (Iris), and add a cURL (Iris) source for reading the turn back. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

therealaditigupta and others added 3 commits October 22, 2026 18:49

MOD-20119: Lead the Lens tagline with debugging agent answers

bb5e133

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

therealaditigupta marked this pull request as ready for review October 23, 2026 10:05

therealaditigupta requested a review from mich-elle-luna October 23, 2026 10:20

mich-elle-luna added the iris Iris context engine docs label Oct 23, 2026

mich-elle-luna self-assigned this Oct 23, 2026

mich-elle-luna approved these changes Oct 23, 2026

View reviewed changes

mich-elle-luna reviewed Oct 23, 2026

View reviewed changes

Navigation Menu

Repository navigation

MOD-20119: Lens developer docs - #4329

MOD-20119: Lens developer docs#4329
therealaditigupta wants to merge 9 commits into
iris-ga-docsfrom
MOD-20119-iris-lens-developer-docs

therealaditigupta commented Oct 23, 2026 •

edited by cursor Bot

Loading

Uh oh!

CLAassistant commented Oct 23, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 23, 2026 •

edited by atlassian Bot

Loading

Summary

Uh oh!

mich-elle-luna left a comment

Uh oh!

mich-elle-luna left a comment

Uh oh!

mich-elle-luna Oct 23, 2026

Uh oh!

mich-elle-luna Oct 23, 2026

Uh oh!

mich-elle-luna Oct 23, 2026

Uh oh!

mich-elle-luna Oct 23, 2026

Uh oh!

mich-elle-luna Oct 23, 2026

Uh oh!

mich-elle-luna Oct 23, 2026

Uh oh!

mich-elle-luna Oct 23, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	- Background export: Your agent doesn't wait on Lens, and a failed export doesn't raise into your agent.
	- 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.

-Open one Lens turn around each agent run, and the steps inside it join the turn. These examples need the Lens connection values from the [quickstart](/content/develop/ai/context-engine/lens/quickstart.md#configure-the-sdk). The framework examples also need a model provider key, such as `OPENAI_API_KEY`.
+To trace an agent run in Lens, open a turn around it. Each step the agent takes inside the run, such as a memory recall or a model call, is recorded in that turn. For more about turns and steps, see [Lens concepts](/content/develop/ai/context-engine/lens/concepts.md).
+Before you start, get the Lens connection values from the [quickstart](/content/develop/ai/context-engine/lens/quickstart.md#configure-the-sdk). The framework examples also need a model provider key, such as `OPENAI_API_KEY`.


		## Trace one turn across Iris products

		When your agent uses Agent Memory, Agent Playbooks, and Context Gateway, one Lens turn shows how each shaped the answer. This example needs the connection values for each Iris product.


		`workflows.turn()` runs each product's context step before the model and its write-back after. Every product call joins the turn:

		{{< clients-example set="iris_lens_iris_products" step="iris_products_turn" description="" lang_filter="Python (Iris)" footer="hide" />}}


		Wrap the handler for one message in `lens.turn()`, and set the outcome on each path:

		{{< clients-example set="iris_lens_own_loop" step="own_loop_turn" description="" lang_filter="Python (Iris)" footer="hide" />}}

	description: Debug agent answers by tracing the context behind each turn, from retrieval to prompt.
	description: Debug AI agent answers by tracing the context behind each turn, from retrieval to prompt.


		## What is Lens?

		Lens shows why your AI agent answered the way it did. For each turn, it records what each source returned, what entered the prompt, which model and tool calls ran, how long each step took, and how the turn ended.

Conversation

therealaditigupta commented Oct 23, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

In this PR

Verification

Open items

Uh oh!

CLAassistant commented Oct 23, 2026

Uh oh!

github-actions Bot commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 23, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧠 Redis Memory

Summary

Uh oh!

mich-elle-luna left a comment

Choose a reason for hiding this comment

Uh oh!

mich-elle-luna left a comment

Choose a reason for hiding this comment

Uh oh!

mich-elle-luna Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

mich-elle-luna Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

mich-elle-luna Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

mich-elle-luna Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

mich-elle-luna Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

mich-elle-luna Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

mich-elle-luna Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

therealaditigupta commented Oct 23, 2026 •

edited by cursor Bot

Loading

github-actions Bot commented Oct 23, 2026 •

edited

Loading

github-actions Bot commented Oct 23, 2026 •

edited by atlassian Bot

Loading