Agents docs: add chat agents, retries, and sync with SDK changes#28378
Merged
Conversation
Add comprehensive Chat agents and Retries reference pages. Update numerous API examples to use TypeScript "} satisfies ExportedHandler<Env>;" for exported handlers. Change Wrangler compatibility_date to a placeholder "$today". Add MCP client retry options and a custom OAuth provider example. Update queue API docs to mark several methods as synchronous and adjust signatures, and add a note about built-in queue retries. Miscellaneous related doc fixes and clarifications.
threepointone
requested review from
elithrar,
irvinebroque,
rita3ko,
thomasgauvin and
whoiskatrin
as code owners
February 16, 2026 19:51
github-actions
Bot
added
product:agents
github-actions
Bot
assigned
elithrar,
irvinebroque,
rita3ko,
thomasgauvin and
whoiskatrin
Contributor
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
Contributor
Simplify Agent class examples in the agents docs by removing explicit generic type parameters (e.g. <Env>, <Env, never>) from class declarations. Updated multiple MDX files under src/content/docs/agents to match the current Agent API/signature and improve example readability. No runtime or behavioral changes — only documentation/type examples were adjusted.
Replace references to `.dev.vars` with `.env` across Agents documentation and update corresponding command examples (touch/echo/cat) and troubleshooting notes. Files updated: src/content/docs/agents/api-reference/configuration.mdx, src/content/docs/agents/guides/remote-mcp-server.mdx, src/content/docs/agents/guides/slack-agent.mdx, and src/content/docs/agents/index.mdx to standardize local development secrets guidance.
Maddy-Cloudflare
approved these changes
Feb 16, 2026
Reword the AIChatAgent lifecycle section to clarify that overriding onConnect/onClose is for adding custom logic while stream resumption, message sync, and connection cleanup are handled automatically. Updated the example comments to remove the implication that calling super is required. Also reformatted the deprecated APIs table for consistent column alignment and readability.
Add new page documenting `shouldSendProtocolMessages` and `isConnectionProtocolEnabled` for per-connection control of protocol text frames. Update cross-references in agents-api, websockets, readonly-connections, store-and-sync-state, and mcp-client-api pages. Corresponds to cloudflare/agents#920. Co-authored-by: Cursor <cursoragent@cursor.com>
Oxyjun
reviewed
Feb 17, 2026
Oxyjun
reviewed
Feb 17, 2026
Oxyjun
reviewed
Feb 17, 2026
Oxyjun
reviewed
Feb 17, 2026
Oxyjun
reviewed
Feb 17, 2026
Oxyjun
reviewed
Feb 17, 2026
Oxyjun
reviewed
Feb 17, 2026
Oxyjun
approved these changes
Feb 17, 2026
Co-authored-by: threepointone <threepointone@users.noreply.github.com>
Contributor
|
Added an introductory sentence before the table at line 105 explaining what it shows, as requested by the reviewer. |
Document data-* stream parts: server-side writer.write() usage, three patterns (reconciliation, append, transient), typed client access via UIMessage generics, and onData callback for transient parts. Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Major update to the Agents SDK documentation, syncing with changes from the
agentsrepo through 0.4.1 and upcoming unreleased features.New pages
api-reference/chat-agents.mdx— Full API reference forAIChatAgentanduseAgentChatfrom@cloudflare/ai-chat. Covers server API, client API, three tool patterns (server-side, client-side, approval), resumable streaming, storage management, multiple AI providers, and advanced patterns (prepareStep, middleware, subagent delegation). Also includes a deprecated APIs table.api-reference/retries.mdx— Reference forthis.retry()with exponential backoff and jitter, per-task retry options forqueue()/schedule()/scheduleEvery(), class-level defaults, MCP server retries, and common patterns.api-reference/protocol-messages.mdx— Reference forshouldSendProtocolMessages()andisConnectionProtocolEnabled(). Covers per-connection suppression of protocol text frames (identity, state, MCP servers) for binary-only clients like MQTT devices. Includes API reference, examples (query param, WebSocket subprotocol, combining with readonly), and how-it-works section. Corresponds to cloudflare/agents#920.Rewritten pages
getting-started/build-a-chat-agent.mdx— Complete rewrite as a proper Diátaxis tutorial. Now uses Workers AI (no API key needed), modern@cloudflare/ai-chatimports, demonstrates all three tool patterns, and includes both server and client code the reader writes themselves. Replaces the old starter-template walkthrough.Updated pages
api-reference/websockets.mdx— Added lifecycle hooks table,onStarthook documentation, connection tags withgetConnectionTags(), hibernation section (what persists, how to disable), common patterns (presence tracking, chat room), and a note in "Handling binary data" linking to protocol messages for binary-only clients.api-reference/mcp-client-api.mdx— AddedcreateMcpOAuthProvider()section for custom OAuth providers,retryoption toaddMcpServer()API reference, and a note that MCP server list broadcasts respect the protocol messages filter.api-reference/schedule-tasks.mdx— UpdatedscheduleSchemato discriminated union shape with ISO 8601 string dates. UpdatedgetSchedule()/getSchedules()signatures from async to synchronous. Updated comparison table (retries now "Built-in").api-reference/queue-tasks.mdx— Updateddequeue(),dequeueAll(),dequeueAllByCallback(),getQueue(),getQueues()signatures from async to synchronous. Replaced "No built-in retry" limitation with a note pointing to the retries page.api-reference/agents-api.mdx— Added "Protocol messages" row to the server-side API reference table.api-reference/store-and-sync-state.mdx— Clarified thatsetState()broadcasts exclude connections whereshouldSendProtocolMessagesreturnedfalse.api-reference/readonly-connections.mdx— Added cross-reference to protocol messages in "Related resources" and "How it works" sections.getting-started/add-to-existing-project.mdx— Added@callable()decorators to CounterAgent example (required foragent.stub.increment()calls shown later in the page).Cross-cutting changes (all agents docs)
satisfies ExportedHandler<Env>added to everyexport default { ... }block across 16 files (35 occurrences). Ensures type safety in all code examples.compatibility_dateupdated to"$today"across 6 files (7 occurrences). Replaces hardcoded dates like"2025-01-01"and"2026-01-28".Notes for reviewers
chat-agents.mdxis ~1,065 lines. It is a Reference page (Diátaxis) covering the full@cloudflare/ai-chatsurface. The previousbuild-a-chat-agent.mdxtutorial was the only chat docs — now there is a proper tutorial and a proper reference.retries.mdxpage documents an unreleased feature (retry-utilitieschangeset). It should land alongside or after the next agents SDK release.protocol-messages.mdxpage documentsshouldSendProtocolMessages/isConnectionProtocolEnabledfrom cloudflare/agents#920, now merged to main.getSchedule,getQueue, etc. droppingasync) are also unreleased (sync-getterschangeset). The oldawaitusage is backward-compatible, but the signatures are now accurate.scheduleSchemadiscriminated union change is unreleased (many-turkeys-sitchangeset).createMcpOAuthProviderwas shipped in 0.4.0 but never documented.chat-agents.mdxcovers deprecations from theai-chat-refactorchangeset.