MOD-19391: Redis Agent Playbooks developer docs by tylerhutcherson · Pull Request #4249 · redis/docs

tylerhutcherson · 2026-10-12T19:49:46Z

MOD-19391 — Redis Agent Playbooks developer documentation.

Adds eleven developer pages for publishing and retrieving approved FAQs, managing reusable skills, reviewing proposals and evidence, and supplying playbook knowledge before and during an agent turn. Examples focus on the published unified Python SDK, HTTP, and the real Iris CLI. TypeScript examples are withheld until a comparable unified SDK is available; the quickstart links separately to the generated package on npm.

Scope

Overview, concepts, quickstart, FAQ and skill management, Proposals, retrieval, Model Context Protocol (MCP), agent integration, limits/errors, and the public data-plane reference.
A Redis Agent Memory-style landing page and four diagrams covering version publication, progressive skill disclosure, proposals, and agent integration. The proposal diagram labels both the inbox review and trash retention windows as 30 days by default, including its accessible description.
55 example blocks and 153 rendered language panels using the existing tabbed-example components. TypeScript tabs, install/run instructions, and the bulk-deletion method column are removed. Existing TypeScript source fixtures and compatibility checks remain for later reuse but are not rendered in the guides.
Python installs redis-iris==0.1.0a4, uses unified discovery/skill helpers, and exposes management operations through the public .client property. Python requires 3.11+. The published unified package depends on redis-agent-playbook==0.1.0a3.
47 CLI panels across the quickstart, FAQ management, skill management, proposal lifecycle, and retrieval. They invoke iris agent-playbook or iris --json agent-playbook directly, retain JSON/file preparation, reconcile keyed entries without automatic publication, and publish explicit reviewed versions. Proposal examples preserve source/evidence files and pass the reviewed revision.
Extraction concepts and FAQ proposal automation guidance through Redis Agent Memory or direct proposal/evidence APIs. Skill extraction remains future work. Proposals emphasizes reviewer and agent value while retaining caller-facing limitations rather than detailing the internal pipeline.
MCP and framework examples keep their protocol/framework focus. CLI batch lookup, reader-only skill loading, digest output, and structured error gaps are qualified in the guides and tracked in redis/redis-iris#39.
The generated data-plane reference and source lock remain tied to the tested alpha.3 contract. The data-plane wire contract matched Iris service revision e883781f69bf9e4ae426b2dd33bcf6fa159c8d32 during the October 21 audit. Pins describe the tested examples rather than claiming every generated package is the newest release.

Rebase and review readiness

Rebased all 17 developer-documentation commits onto main at 115a3c5ec1fb12e2aebd1da80e93bcd8ace25fd3 without conflicts. Range comparison confirms that the Playbooks content and programs are preserved while retaining main's navigation updates.
Browser validation caught a quickstart table-of-contents error: heading IDs beginning with a digit fail the site's CSS-selector lookup. Commit 7520513f6102b62bdce8a655b6de93745c0f5d78 removes the five heading-number prefixes and adds a regression check. Example programs are unchanged, and no repository links targeted the former numbered anchors.
The developer PR is ready for review, not draft/WIP. No merge or publication is performed by this update.

Validation

Post-rebase validation on October 22:

python -m pytest build/agent_playbook_docs -q: 139 passed on the rebased content. After the heading-only correction and new regression test, python -m pytest build/agent_playbook_docs/test_reference.py -q: 8 passed. Together these cover all 140 current suite tests; the executable programs are unchanged by the follow-up.
python -m pytest build/test_cli_parser.py build/test_command_lists.py -q: 19 passed for the shared example-parser and command-list helpers.
SDK source-lock checks, fresh example generation, strict TypeScript compilation of retained fixtures, and git diff --check pass. Dependencies were installed in a fresh Python 3.12 environment and with the checked-in npm lockfile.
Full Hugo extended 0.143.0 build passed: 20,227 pages, including a rebuild after the navigation correction. No Playbooks-specific build errors or warnings; existing warnings elsewhere remain outside scope.
Browser checks passed across all 11 developer pages, 55 example blocks, and 153 remaining panels, with TypeScript absent from the selectors. All 36 API-reference operations render under main's pinned Redoc v2.5.4 viewer.
653 internal links/anchors and image paths resolved. After the quickstart correction, every table-of-contents selector resolves and clicking the FAQ creation link reaches #create-an-faq without application errors.
Earlier bottom-up audit: 32 live smoke cases passed against fresh control plane, data plane, and Identity Service binaries built from Iris revision e883781f69bf9e4ae426b2dd33bcf6fa159c8d32. Cases cover core SDK/cURL/CLI workflows, reader-only retrieval, MCP, async Python, and complete-program copies; each provisions and removes its own playbook and scoped keys. Rebase and presentation changes do not alter those programs.

Validation boundaries and follow-ups:

Live checks use test/noop embeddings, so they verify API behavior, not semantic relevance or live model quality. Framework tests use controlled model responses. A live background-extraction deployment is not claimed as validated here.
Cloudflare Turnstile rejects the temporary localhost preview hostname; the Ask AI backend is not part of this local validation.
npm audit reports one existing low-severity transitive esbuild advisory concerning its development server on Windows (GHSA-g7r4-m6w7-qqqr). The rebase does not change that dependency lockfile; no dependency update is bundled into this docs review.
This documentation repository has no Taskfile or Iris-specific lint/test tasks. Validation uses its dedicated Playbooks suite, shared parser checks, and supported Hugo build.

Latest developer commit: 7520513f6102b62bdce8a655b6de93745c0f5d78 — docs: fix Playbooks quickstart navigation. Rebased cleanup: 428b113da; direct Iris CLI commands: 12bd46903; Proposals editorial pass: c51fa409f; unified Python/CLI migration: 05a9897e5.

Stack and publication

Foundation: MOD-19391-playbook-developer-docs → main (this PR), ready for review.
Child: #4256 — Redis Agent Playbooks self-managed operator docs, still draft. Its branch is unchanged and needs rebasing onto the rewritten developer branch before reviewing its remaining diff. Operator audit findings remain separate work.
Merge the developer PR first, then rebase/retarget the operator PR onto main.

Neither PR is merged. Merging into main publishes the documentation; repository and staging previews are public. Review readiness is not launch publication approval.

Note

Low Risk
Changes are documentation, example sources, and CI validation tooling; they do not alter production services, though incorrect SDK pins or contract drift would fail checks rather than ship silently.

Overview
Adds the Redis Agent Playbooks developer section under Context Engine: overview, concepts, quickstart, FAQ/skill/proposal guides, retrieval, MCP, agent integration (OpenAI Agents / LangGraph), limits, and a Redoc-backed data-plane API reference tied to a checked-in OpenAPI contract.

Introduces build/agent_playbook_docs, which locks the published contract to iris-sdks (source-lock.json, check_sdk_source.py), assembles tabbed examples from local_examples/iris/playbooks and clients-example markup (examples.py), and runs a large pytest suite against schema-checked HTTP fixtures plus controlled agent/MCP/CLI runs; live_examples.py supports optional end-to-end runs against a local stack. A path-filtered GitHub Action check-playbook-docs.yml runs lock checks, example generation, TypeScript compile of generated fixtures, and the suite on relevant PRs.

Extends the docs example pipeline for Iris: Python (Iris), cURL, CLI, and internal TypeScript/bash handling in local_examples.py, example.py, clients.tsv, and config.toml, while the guides emphasize unified Python SDK, HTTP, and iris agent-playbook CLI (TypeScript tabs withheld from published pages). Updates the Context Engine landing page to surface Playbooks and softens deployment wording.

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

CLAassistant · 2026-10-12T19:49:55Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ andy-stark-redis
❌ tylerhutcherson
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

github-actions · 2026-10-12T19:50:04Z

github-actions · 2026-10-12T19:50:08Z

🧠 Redis Memory

Found 12 related items from repository history:

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 — MOD-18528: Document Playbook bindings and RAM service-subject authentication

Summary
Commit — Rework Iris concepts pages for newcomer audiences and Google style

Rework Iris concepts pages for newcomer audiences and Google style
PR — DOC-6809 Docs-only MCP server: spec + v0 prototype

Note: not finished - just using the PR for Bugbot feedback so far.
PR — DOC-7121 Consolidate agent-memory Python/TypeScript SDK quickstarts into one TCE page

Summary
PR — WIP: Playbook self-managed operator docs

MOD-19679 — Self-managed Redis Agent Playbooks operator documentation.
Commit — docs(iris): refine Playbooks developer guides and examples

docs(iris): refine Playbooks developer guides and examples
Commit — docs: add self-managed Agent Playbooks operator guides

docs: add self-managed Agent Playbooks operator guides
Commit — docs: simplify Playbooks MCP examples and guide navigation

docs: simplify Playbooks MCP examples and guide navigation
Commit — docs: clarify Redis Agent Playbooks terminology

docs: clarify Redis Agent Playbooks terminology
Commit — docs: align Playbooks operator guides with Iris main

docs: align Playbooks operator guides with Iris main
Commit — docs: add unified Python and CLI Playbooks examples

docs: add unified Python and CLI Playbooks examples

Memory updated at 7520513

mich-elle-luna · 2026-10-13T18:35:50Z

This needs the same re-base as the other PR in this stack to get the new nav and look/feel.

I've also added Andy and Paolo for their review of the build changes proposed here and anything else they see. In case we can pull off some interactive demo of this component and also to get more eyes on this in the final sprint.

andy-stark-redis

@tylerhutcherson The language mainly looks OK but I've made a few comments here and there. However, the PR seems to invent a whole new system for supplying the code examples when we already have a really good one available :-)

I've added a new commit to enable three new language variants in the docs for Iris Python, TS, and cURL examples (they are listed as if they were "clients" because that is what we mainly deal with in the docs). We have a Claude skill for adding tabbed code examples (TCEs), so if you ask for the examples to be reworked in this form, it should know what you mean. The example source files should be placed in local_examples/iris.

The TCE boxes on the published page allow you to copy the full text of the example rather than download, so any surrounding body text that refers to downloading example files will need to be removed. Some of the build scripts you've added will also be unnecessary when the examples are redone as TCEs.

If you encounter any problems with this then just let me know and I'll be happy to help out.

tylerhutcherson · 2026-10-14T15:10:35Z

@tylerhutcherson The language mainly looks OK but I've made a few comments here and there. However, the PR seems to invent a whole new system for supplying the code examples when we already have a really good one available :-)

I've added a new commit to enable three new language variants in the docs for Iris Python, TS, and cURL examples (they are listed as if they were "clients" because that is what we mainly deal with in the docs). We have a Claude skill for adding tabbed code examples (TCEs), so if you ask for the examples to be reworked in this form, it should know what you mean. The example source files should be placed in local_examples/iris.

The TCE boxes on the published page allow you to copy the full text of the example rather than download, so any surrounding body text that refers to downloading example files will need to be removed. Some of the build scripts you've added will also be unnecessary when the examples are redone as TCEs.

If you encounter any problems with this then just let me know and I'll be happy to help out.

Updating to use the existing TCE structure and format!

…amples Adds three TCE pseudo-client keys, "Python (Iris)", "TypeScript (Iris)", and "cURL (Iris)", so Iris examples can use the standard clients-example system instead of multitabs. Each key is the visible tab title and is shared across all Iris products, so names avoid any one SDK package. - config.toml: keys in clientsExamples and clientsConfig, modeled on RedisVL. Own clientId (iris-python/-typescript/-curl), empty quickstartSlug and mappingClientId, so tabs don't carry redis-py or node-redis identity in the code-examples JSON metadata. - build/local_examples.py: .ts/.mts -> typescript, .sh -> bash; a path containing 'iris' selects the Iris client (put sources under local_examples/iris/). .mts keeps top-level await working under tsx. Non-Iris .ts/.sh files resolve to no configured client. - build/components/example.py: comment prefixes for typescript (//) and bash (#); without them Example() rejects the language. Verified with a throwaway three-language set: the build tagged each file with the right client and Hugo rendered the tabs with correct step slices, lexers, full-file templates, and clientId/clientName. The test set was removed; no pages are converted in this commit. Gotcha: get_example_id_from_file reads only line 1, so .sh sources must start with "# EXAMPLE:" and cannot carry a shebang. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Discover turn context through the SDK before running OpenAI Agents SDK or LangGraph. Keep standard MCP clients and tool guidance on the existing MCP page, and suppress drafts while tool failures remain unresolved.

cursor

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7520513. Configure here.}

cursor · 2026-10-22T20:49:00Z

+      - 'config.toml'
+      - 'layouts/partials/process-markdown-content.html'
+      - 'layouts/_default/apireference.html'
+      - '.github/workflows/check-playbook-docs.yml'


CI ignores Playbooks diagram asset changes

Medium Severity

The Playbooks docs workflow path filters omit static/images/ai/context-engine/. test_proposal_diagram_qualifies_default_retention_windows reads agent-playbook-proposals.svg, so a diagram-only edit that drops the default 30-day labels would not run that check.

Additional Locations (1)

build/agent_playbook_docs/test_reference.py#L64-L71

^{Reviewed by Cursor Bugbot for commit 7520513. Configure here.}

mich-elle-luna

thank you!

tylerhutcherson mentioned this pull request Oct 12, 2026

WIP: Playbook developer docs #4248

Closed

tylerhutcherson mentioned this pull request Oct 13, 2026

WIP: Redis Agent Playbooks self-managed operator docs #4256

Draft

tylerhutcherson added documentation Improvements or additions to documentation iris Iris context engine docs dev labels Oct 13, 2026

mich-elle-luna requested review from andy-stark-redis and paoloredis October 13, 2026 18:19

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

mich-elle-luna self-requested a review October 13, 2026 18:20

andy-stark-redis requested changes Oct 14, 2026

View reviewed changes

Comment thread content/develop/ai/context-engine/agent-playbook/_index.md Outdated

Comment thread content/develop/ai/context-engine/agent-playbook/faqs.md Outdated

Comment thread content/develop/ai/context-engine/agent-playbook/faqs.md Outdated

tylerhutcherson force-pushed the MOD-19391-playbook-developer-docs branch from c0ef4a2 to d7293c3 Compare October 14, 2026 18:45

tylerhutcherson changed the title ~~WIP: Playbook developer docs~~ WIP: Redis Agent Playbooks developer docs Oct 15, 2026

nkanu17 mentioned this pull request Oct 22, 2026

RED-220418: Add Context Gateway developer docs #4323

Merged

tylerhutcherson and others added 12 commits October 22, 2026 16:31

docs: scaffold Agent Playbooks guides and review handoff

85cd136

docs(iris): refine Playbooks developer guides and examples

114112c

docs: align Playbooks navigation with the Iris docs space

eb745e9

docs: give the FAQ authoring guide a task-specific URL

e2f9e31

docs: simplify cross-language naming explanations

6c6a2b9

docs: use standard TCE sources for Playbooks examples

c442956

docs: separate Playbooks MCP and agent integration guides

67f9016

Discover turn context through the SDK before running OpenAI Agents SDK or LangGraph. Keep standard MCP clients and tool guidance on the existing MCP page, and suppress drafts while tool failures remain unresolved.

docs: simplify Playbooks MCP examples and guide navigation

03da1f1

docs: improve Playbooks navigation and Python examples

f5a1e09

docs: add Playbooks workflow diagrams

b07e7ee

docs: clarify Redis Agent Playbooks terminology

772939a

tylerhutcherson added 6 commits October 22, 2026 16:31

docs: align Playbooks guides with alpha.3 SDKs

9996b99

docs: add unified Python and CLI Playbooks examples

05a9897

docs: focus Proposals guide on reusable agent knowledge

c51fa40

docs: show Iris CLI commands directly

12bd469

docs: simplify Playbooks examples and fix retention diagram

428b113

docs: fix Playbooks quickstart navigation

7520513

tylerhutcherson force-pushed the MOD-19391-playbook-developer-docs branch from fafb18d to 7520513 Compare October 22, 2026 20:39

tylerhutcherson changed the title ~~WIP: Redis Agent Playbooks developer docs~~ MOD-19391: Redis Agent Playbooks developer docs Oct 22, 2026

tylerhutcherson marked this pull request as ready for review October 22, 2026 20:39

tylerhutcherson changed the base branch from main to iris-ga-docs October 22, 2026 20:46

cursor Bot reviewed Oct 22, 2026

View reviewed changes

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

View reviewed changes

tylerhutcherson merged commit d6d2388 into iris-ga-docs Oct 22, 2026
103 of 104 checks passed

tylerhutcherson deleted the MOD-19391-playbook-developer-docs branch October 22, 2026 22:33

atlassian Bot mentioned this pull request Oct 23, 2026

Consolidate Agent Memory documentation for GA #4001

Draft

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

MOD-20119: Lens developer docs #4329

Open

tylerhutcherson mentioned this pull request Oct 23, 2026

MOD-20121: Align Playbook extraction authentication setup #4330

Draft

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

MOD-20121: Update Playbook operator extraction setup #4331

Draft

Navigation Menu

Repository navigation

MOD-19391: Redis Agent Playbooks developer docs - #4249

MOD-19391: Redis Agent Playbooks developer docs#4249
tylerhutcherson merged 18 commits into
iris-ga-docsfrom
MOD-19391-playbook-developer-docs

tylerhutcherson commented Oct 12, 2026 •

edited by cursor Bot

Loading

Uh oh!

CLAassistant commented Oct 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 12, 2026 •

edited by atlassian Bot

Loading

Summary

Summary

Uh oh!

mich-elle-luna commented Oct 13, 2026

Uh oh!

andy-stark-redis left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tylerhutcherson commented Oct 14, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Oct 22, 2026

Uh oh!

mich-elle-luna left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

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

Uh oh!

Scope

Rebase and review readiness

Validation

Stack and publication

Uh oh!

CLAassistant commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

🧠 Redis Memory

Summary

Summary

Uh oh!

mich-elle-luna commented Oct 13, 2026

Uh oh!

andy-stark-redis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tylerhutcherson commented Oct 14, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Oct 22, 2026

Choose a reason for hiding this comment

CI ignores Playbooks diagram asset changes

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!

4 participants

tylerhutcherson commented Oct 12, 2026 •

edited by cursor Bot

Loading

CLAassistant commented Oct 12, 2026 •

edited

Loading

github-actions Bot commented Oct 12, 2026 •

edited

Loading

github-actions Bot commented Oct 12, 2026 •

edited by atlassian Bot

Loading