RED-220418: Add Context Gateway developer docs by nkanu17 · Pull Request #4323 · redis/docs

nkanu17 · 2026-10-22T02:42:21Z

Summary

redis.io has no Context Gateway pages, and its Context Retriever pages describe a product that Context Gateway replaces. This PR adds 20 Context Gateway pages in a Diátaxis layout (concepts, tutorial, how-to guides, reference) and removes the Context Retriever docs, redirecting every old URL to the matching Context Gateway page.

The page set copies the sibling products. Developer pages follow Agent Playbooks (MOD-19391: Redis Agent Playbooks developer docs #4249): overview, concepts, quickstart, task guides, MCP, agent integration, API reference, limits. The developer guide follows Agent Memory's. Operator pages follow the Agent Memory self-managed set, as the Iris AGENTS.md asks.
Clients match MOD-19391: Redis Agent Playbooks developer docs #4249 as of fafb18d15: Python (Iris) with redis-iris, cURL (Iris), and CLI (Iris) with iris context-gateway. The developer guide also names the generated TypeScript client on npm.
Install commands use the newest published releases, redis-iris==0.1.0a4 (which pins redis-context-gateway==0.1.0a4) and @redis-iris/context-gateway@0.1.0-alpha.4. One TODO in the quickstart marks the move to 0.1.0a5.
The pages say up front that an Upstream is any MCP server reachable over Streamable HTTP. A Context Surface is the optional Redis kind and has its own how-to.
The developer API reference documents the MCP surface: tools and arguments, _meta keys, JSON-RPC errors and tool-result failures, protocol versions.
An independent review against Agent Memory, Agent Playbooks, the Iris rules and the product sources drove the second commit. It fixed three factual errors, added the missing pages and sections, and aligned names.
Context Retriever: 11 pages, its embed, and its demo shortcode and script are deleted. Links and tiles on 16 pages now point at Context Gateway, and aliases redirect each old URL.

flowchart LR
    L["Overview"] ==> C["Concepts"]
    L ==> G["Developer guide"]
    L ==> Q["Quickstart"]
    Q ==> M["Manage Gateways"]
    Q ==> S["Manage Context Surfaces"]
    Q ==> X["MCP"]
    X ==> A["Agent integration"]
    X ==> R["API reference"]
    R ==> E["Limits and errors"]
    O["Self-managed"] ==> P["Prerequisites"] ==> CF["Configuration"] ==> D["Deploy"] ==> AU["Authentication"] ==> AE["API examples"]
    AE ==> Q

Where it sits: targets the iris-ga-docs feature branch, where the Iris GA docs PRs are staged together before one merge to main. It is separate from #4249 and #4256, which target the same branch. It needs the Iris tab definitions from #4249 only when the runnable examples replace the placeholders.

Review first: the Context Retriever removal (the last commit), because it deletes published Redis Cloud pages. Then the concepts page and the API reference, which carry the product claims.

Detail follows.

Ticket ID

RED-220418: Context Gateway docs on the website.

Commits

b0c3771ab docs(iris): add Context Gateway developer and self-managed docs
5ac63cc4b docs(iris): apply the Context Gateway docs review
5db6186a8 Merge main
ca516ad7b docs(iris): remove the Context Retriever docs in favor of Context Gateway

Pages

Developer section, content/develop/ai/context-engine/context-gateway/:

Page	Type	What it covers
`_index.md`	Overview	Landing page in the Context Retriever landing shape, a note that Upstreams are not limited to Redis, and link lists for every page.
`concepts.md`	Concepts	Gateways and access, Upstreams and namespaces, catalogs, credentials, tool exposure modes, tool policies, result cache, result handles, key terms. Three diagrams.
`developer-guide.md`	Concepts and how-to	Integration workflow, choose a client (Python, CLI, TypeScript, HTTP), connect to a Gateway, work with tools and large results.
`quickstart.md`	Tutorial	A clinic front-desk scenario over two Gateways: list, call, search, a handle, and async Python. No administrator step mid-flow.
`manage-gateways.md`	How-to	Create, list, change, and delete Gateways and MCP server Upstreams, enable or disable, tool policies, credential rotation.
`manage-context-surfaces.md`	How-to	Data model, create, `initialCatalogFailure`, generated tools, change or refresh, delete and the stuck-delete option.
`mcp.md`	How-to	Streamable HTTP settings, `search_tools` and `run_tool`, result handles, identity provider sign-in, troubleshooting. One diagram.
`agent-integration.md`	How-to	OpenAI Agents SDK and LangGraph, Python only as in #4249, with the clinic task. One diagram.
`api-reference.md`	Reference	The MCP API: endpoint, tools and arguments, `_meta` keys, JSON-RPC errors and tool-result failures.
`limits.md`	Reference	Tool and result limits, failure reasons and `completion`, Control Plane errors, conflicts, retries.

Operator section, content/operate/iris/context-gateway/:

Page	Type	What it covers
`_index.md`	Overview	Landing page for the operator side.
`self-managed/_index.md`	Concepts	What you deploy, how the components work together, API surfaces, manage the deployment.
`self-managed/prerequisites.md`	Reference	Software, Redis databases with JSON and Search requirements, Surface database Redis users, credential storage, network and ingress for Streamable HTTP, images, air-gapped installs.
`self-managed/configuration.md`	Reference	Helm values, file references including Vault, credential storage and the keyring, database registry, Context Surface databases and embeddings, result cache and handle settings, security and tracing, scaling.
`self-managed/deploy.md`	How-to	Eight numbered steps from namespace to one authenticated MCP call, with a "check your values" table.
`self-managed/authentication.md`	How-to and reference	`## Credentials` table, the admin token, Gateway grants, identity provider sign-in and subject grants.
`self-managed/api-examples.md`	How-to	Create the two quickstart Gateways and the sample Upstream, mint an agent key, rotate or revoke keys, and the CLI equivalent.
`self-managed/control-plane-api-reference.md`	Reference	Generated from the published Control Plane OpenAPI contract, unedited.
`self-managed/operations.md`	How-to	Health, credential and keyring rotation, result cache monitoring, the Gateway database, backups, upgrades, uninstall.
`self-managed/reference.md`	Reference	Configuration files, external secret managers, troubleshooting, chart references.

Description

1. The layout follows the sibling products.

The Iris AGENTS.md (from #4312) names the pages to copy for each page type. The landing page copies Context Retriever's. The self-managed set copies Agent Memory's, so it has no separate "plan your deployment" page. Developer task pages, mcp.md, limits.md and the quickstart copy #4249, and developer-guide.md copies Agent Memory's.

2. Three factual errors from the first commit are fixed.

Result handles are on for every eligible result once a deployment turns them on, and a tool opts out with resultHandle.capture: never. The first commit called them a per-tool opt-in.
unknown_tool, invalid_request and gateway_unavailable on tools/call come back as JSON-RPC errors with error.data.reason and traceId. The first commit called every failure a tool result.
The CLI's dry-run option exists only on service delete, not on service create.

3. Clients and versions match #4249.

#4249 moved this week to the unified redis-iris package and the Iris CLI, and withheld TypeScript tabs. These pages do the same. The developer guide still names the generated TypeScript client, @redis-iris/context-gateway, as Agent Memory's developer guide names its TypeScript SDK. The Python examples reach the SDK only through ContextGateway's client and service properties, so the 0.1.0a5 rename of the SDK's data-plane client doesn't break them. The one a5 TODO in quickstart.md stays as is.

4. "Upstream" stays the term.

The API (/upstreams, upstreamId), the failure reasons (upstream_*), the SDKs, the CLI (upstream add) and the shipped console ("Add an Upstream") all use it. Each page defines it at first use and names the two kinds right away.

5. Context Surface limits are stated as current behavior.

Every agent with access to a Gateway can read every record of every Surface on it.
Gateways whose Surfaces share a database can read each other's records.
Indexing runs in the background, so search tools can return partial results until it finishes.
Surface tools return at most 100 records per call.
All callers share a Gateway's cache entries.

6. Context Retriever is removed.

Deleted: 4 developer pages, 5 operator pages, the Redis Cloud bridge page, content/embeds/rc-context-retriever-get-started.md, layouts/shortcodes/context-retriever-demo.html, and static/js/context-retriever-demo.js. static/css/context-retriever-demo.css stays, because the Iris and RDI demos share it.
Redirects: aliases on the Context Gateway landing, concepts, quickstart, operator landing, and self-managed pages cover every deleted URL. build/check_missing_aliases.py, run over all pages, reports nothing for these paths.
Repointed to Context Gateway: the Iris developer and operator landing pages, the AI landing page, agent concepts, Iris concepts, the request-flow map node, the Data Integration landing, the operate landing, the Redis Cloud context engine bridge, and the sample-data sentence on five demo pages.
Kept as plain text: the Context Retriever mentions in whats-new and the May 2026 Redis Cloud changelog, because those are history, and the external tutorial link on the AI landing page.

7. Iris landing tiles.

Both Iris landing pages get a Context Gateway tile with icon-redis-iris-64-duotone.png, the fallback icon the docs team suggested for Agent Playbooks until a product icon exists.

8. Diagrams use the existing Iris Mermaid theme.

Five Mermaid exports with the neo look, #ee0000 borders, #0b0b0b lines and Trebuchet MS, the same style block as the existing Iris concept diagrams. They have transparent backgrounds, so iris-dark.css inverts them like the others. The overview shows the Identity Service, the cache diagram starts with the policy check, and the handles diagram shows automatic capture.

9. No links to internal repositories.

The pages link only public destinations, the same kinds Agent Memory and Agent Playbooks link: package pages on PyPI and npm, the Redis Helm repository, framework docs, and redis.io pages.

Testing

Full Hugo extended 0.143.1 build of the branch: 20,222 pages, no errors, no REF_NOT_FOUND, and no warnings on Context Gateway pages. Existing warnings elsewhere in the repository are outside scope.
Every cross-page anchor on the Context Gateway pages resolves to a heading on its target page.
build/check_missing_aliases.py, run over all pages, reports no missing alias for the renamed or deleted pages.
No em dashes, en dashes, semicolons or double hyphens in the prose of the Context Gateway pages.
Not run: the examples, which are placeholders. The Control Plane API reference renders blank under hugo serve, as the other Iris API reference pages do.

For the docs team

Preview banners on five Iris-wide pages still name Context Retriever. The Iris rules say banner changes go in one pass at launch, so they are left as is.
The Iris interactive demo (static/js/iris-demo.js) still models Context Retriever as one of its services. Its link now points to Context Gateway. Reworking the demo script is a docs-team decision.
The console screenshot on the Iris operator landing page shows a Context Retriever card.
An interactive demo for Context Gateway, like the Agent Memory demo.
The Iris AGENTS.md term tables need Gateway, Upstream, Context Surface and namespace.

Open items, marked as TODO comments in the pages

The published chart version, image tags, supported Kubernetes versions, and minimum Redis version.
How the chart supplies the Context Surface embedding API key.
The keyring rotation check and backup and restore guarantees.
The chart's credential_storage keys and the service README's secrets keys use different names.
Whether the OpenAI Agents SDK and the LangChain MCP adapter rename dotted tool names.
Per-provider identity provider settings, the subject grant request body, and the MCP clients verified to complete sign-in.
The Context Surface data model reference.
The generated OpenAPI carries internal planning notes in a few descriptions. It can't be hand-edited, so the service owners need to fix the source and regenerate.

Follow-ups (out of scope)

These don't block this PR:

Runnable tabbed examples in local_examples/iris/context-gateway/, in Python, cURL and CLI.
A page dedicated to the Iris CLI as a whole, shared by every Iris product.

Stack and publication

Targets iris-ga-docs, cut from the tip of main. It doesn't depend on MOD-19391: Redis Agent Playbooks developer docs #4249 or WIP: Redis Agent Playbooks self-managed operator docs #4256 to build.
Merging into iris-ga-docs stages the pages. Merging that branch to main publishes them and removes the Context Retriever pages. The staging preview for this branch is public.

🤖 Generated with Claude Code

Note

Medium Risk
Removes published Context Retriever (including Redis Cloud operator) pages in favor of new product docs; aliases mitigate broken links but readers following old mental models may be confused until launch banners and demos are updated.

Overview
Replaces Context Retriever documentation with Redis Context Gateway across redis.io: the Iris/AI narrative now describes one MCP endpoint for third-party MCP servers plus optional Context Surfaces over Redis data, instead of a standalone schema-first retriever product.

Adds a full Context Gateway doc set (developer overview, concepts, quickstart, gateway/surface management, MCP, agent integration, API/limits; operator self-managed deploy/configure/auth/operations) and deletes the Context Retriever pages, embed, and interactive demo assets. Aliases on the new pages redirect former Context Retriever URLs; 16+ existing pages (AI/Iris landings, request-flow diagram, demos, operate tiles) are updated to link and describe Context Gateway. Changelog/history entries still mention Context Retriever by name.

Runnable examples remain placeholders; several TODO comments note unpublished chart versions and open product confirmations.

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

Add the Context Gateway pages under develop/ai/context-engine and operate/iris, following the Agent Playbooks and Agent Memory layouts: overview, concepts, quickstart, Gateway management, MCP connection, agent integration, limits, and the self-managed deployment set with the generated Control Plane API reference. Add five Mermaid concept diagrams in the existing Iris diagram theme. Code examples are placeholders until the tabbed examples land.

github-actions · 2026-10-22T02:42:38Z

github-actions · 2026-10-22T02:47:46Z

🧠 Redis Memory

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

PR — Iris concepts

Add four new concepts documents for Iris, RAM, Langcache and CR.
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)
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 — Rework Iris concepts pages for newcomer audiences and Google style

Rework Iris concepts pages for newcomer audiences and Google style
PR — WIP: Redis Agent Playbooks developer docs

MOD-19391 — Redis Agent Playbooks developer documentation.
Commit — docs(iris): add Context Gateway developer and self-managed docs

docs(iris): add Context Gateway developer and self-managed docs
Commit — docs(iris): remove the Context Retriever docs in favor of Context Gateway 🆕

docs(iris): remove the Context Retriever docs in favor of Context Gateway

Memory updated at 2b7a154

Align page names and sections with Agent Memory and Agent Playbooks, fix the facts the review found wrong, and fill the reported gaps. - Rename connect-agents.md to mcp.md (linkTitle MCP), and add the MCP API reference, a developer guide, and a Context Surfaces how-to. - Describe result handles as on for every eligible result once enabled, with a per-tool opt-out, and split tool call failures into JSON-RPC errors and tool results. - Give the API examples, configuration, and operations pages titles, fold the Identity Service step into deploy step 2, and add the missing chart settings, Surface database users, ingress headers, keyring rotation, cache monitoring, and uninstall. - Make the quickstart run without an administrator mid-flow, and add the Context Gateway tile to both Iris landing pages. - Redraw the overview, result cache, and result handles diagrams.

…teway-docs

…eway Delete the Context Retriever developer, operator, and Redis Cloud bridge pages, the shared get-started embed, and the demo shortcode and script that only its demo page used. Redirect every old URL to the matching Context Gateway page with aliases. Repoint the Iris landing pages, concepts, request flow, AI landing, agent concepts, and demo pages from Context Retriever to Context Gateway, and keep historical release notes as plain-text mentions.

mich-elle-luna

thank you!

…ntext-gateway-docs # Conflicts: # content/develop/ai/context-engine/_index.md

nkanu17 requested a review from mich-elle-luna October 22, 2026 02:45

nkanu17 marked this pull request as ready for review October 22, 2026 02:46

nkanu17 added 3 commits October 22, 2026 11:32

Merge remote-tracking branch 'origin/main' into RED-220418/context-ga…

5db6186

…teway-docs

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

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

nkanu17 changed the base branch from main to iris-ga-docs October 22, 2026 22:18

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

View reviewed changes

github-actions Bot mentioned this pull request Oct 23, 2026

MOD-20119: Lens developer docs #4329

Open

Merge remote-tracking branch 'origin/iris-ga-docs' into RED-220418/co…

2b7a154

…ntext-gateway-docs # Conflicts: # content/develop/ai/context-engine/_index.md

nkanu17 merged commit 202acc5 into iris-ga-docs Oct 23, 2026
55 checks passed

nkanu17 deleted the RED-220418/context-gateway-docs branch October 23, 2026 15:59

nkanu17 mentioned this pull request Oct 23, 2026

RED-220418: Open the Context Gateway landing with What is Context Gateway #4343

Merged

Navigation Menu

Repository navigation

RED-220418: Add Context Gateway developer docs - #4323

RED-220418: Add Context Gateway developer docs#4323
nkanu17 merged 5 commits into
iris-ga-docsfrom
RED-220418/context-gateway-docs

nkanu17 commented Oct 22, 2026 •

edited by cursor Bot

Loading

Uh oh!

github-actions Bot commented Oct 22, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 22, 2026 •

edited by atlassian Bot

Loading

Uh oh!

mich-elle-luna left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Summary

Ticket ID

Commits

Pages

Description

Testing

For the docs team

Open items, marked as TODO comments in the pages

Follow-ups (out of scope)

Stack and publication

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

🧠 Redis Memory

Uh oh!

mich-elle-luna left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nkanu17 commented Oct 22, 2026 •

edited by cursor Bot

Loading

github-actions Bot commented Oct 22, 2026 •

edited

Loading

github-actions Bot commented Oct 22, 2026 •

edited by atlassian Bot

Loading