docs(ai-chat): custom agents page, backend decision table, and a building-agents anatomy entry#3921
Conversation
…reference Adds a dedicated Custom agents page covering chat.customAgent (agent registration + session binding) and both loop styles: the managed createSession iterator and the hand-rolled primitives loop. Includes the patterns the managed lifecycle otherwise covers for you: continuation history seeding, persisting the user message before streaming, racing totalUsage after a stop, and the slim wire shape. The Backend page leads with a decision table across the three abstraction levels and now focuses on chat.agent, routing to the new page. Completes the ChatSessionOptions and ChatTurn reference tables (compaction, pendingMessages, usage fields, setMessages, prepareStep) and fixes stale examples that read a plural messages field off the wire payload.
The Building agents group opened with the long How it works mechanics page, which is the wrong first step after the Quick Start. A new Anatomy page now leads the group: the three moving parts (agent task, session, frontend transport), one annotated chat.agent example where each region names the page that covers it, and a routing table for the group. No setup steps, explicitly skippable. How it works moves to the end of the group as the depth payoff, the position peers (Clerk, LangGraph) give their internals pages. Also registers the Custom agents page at the bottom of the group.
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📜 Recent review details⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
WalkthroughThis PR reorganizes the agent documentation to establish a clearer information architecture. It introduces a foundational "anatomy" page explaining the three-part structure (backend loop, session, frontend integration), creates a comprehensive "custom agents" reference covering both managed and hand-rolled execution patterns, consolidates duplicated content in the backend guide, documents new session/turn API options in the reference, redirects all relevant cross-document links to the new structure, and updates navigation to reflect the new pages. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
ESLint install timed out. The project may have too many dependencies for the sandbox. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
Inbound deep links to the sections that moved to the Custom agents page (#chat-createsession, #chat-customagent, #raw-task-with-primitives) now land on the router stub instead of the top of the Backend page. Path-level redirects cannot cover this since fragments never reach the server.
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
2 participants
Summary
Documents the two lower-level chat backend APIs and restructures the Building agents section so it has a sane reading order.
Custom agents page.
chat.customAgent()was effectively undocumented (one passing mention) andchat.createSession()was buried at the bottom of the Backend page, prompted by a customer asking whether dropping down a level was supported at all. Both now live on one dedicated page framed as a composition: register withcustomAgent, then drive turns with the managedcreateSessioniterator or a hand-rolled primitives loop. The page covers the patterns the managed lifecycle otherwise handles for you, each verified against a running agent: seeding history on continuation runs (and why the seed must go through the turn-0addIncoming, which replaces the accumulator), persisting the user message before streaming so a mid-stream reload keeps it, racingtotalUsageafter a stop so the loop cannot wedge, and the single-message wire shape.Backend page. Now leads with a decision table across the three abstraction levels and focuses on
chat.agent(), routing to the new page. Stale examples that read a pluralmessagesfield off the wire payload are fixed (copy-pasting them broke turn accumulation), and the ChatSessionOptions / ChatTurn reference tables gain their missing rows (compaction,pendingMessages, usage fields,setMessages,prepareStep).Anatomy page + reorder. The Building agents group opened with the long How it works mechanics page, a wall right after the Quick Start. A short Anatomy page now leads the group: the three moving parts, one annotated example where each region names the page that covers it, and a routing table. How it works moves to the end of the group as the depth payoff, matching where peer docs put their internals pages.
All pages visually verified against a local Mintlify build; cross-links and anchors updated across the section.