Agents docs: Workers AI first, fix bugs, rewrite key pages#28501
Merged
Conversation
Replace OpenAI-specific examples with Workers AI / AI SDK usage across Agents docs. Examples now use an Env AI binding, createWorkersAI / workers-ai-provider, and streamText/generateText from the ai SDK instead of direct OpenAI clients or API keys. Updated WebSocket/SSE streaming, long-running model examples, and SQL/state persistence to consume this.env.AI.run streams/responses. Updated Wrangler/config mentions to use the ai binding and clarified AI Gateway/model routing guidance. Files changed: browse-the-web.mdx, http-sse.mdx, store-and-sync-state.mdx, using-ai-models.mdx, index.mdx.
Revise agent-class.mdx to clarify the Agent/Server/DurableObject layering, tighten wording, fix small code snippets (ws.send, storage access, Response usage), standardize PartyKit/Server references, and add a new Layer 3 section describing AIChatAgent. Replace calling-llms.mdx with a complete rewrite that focuses on using LLMs inside stateful Agents: explains state-as-context, surviving disconnections, autonomous model calls, multi-model pipelines, and caching; adds multiple TypeScript examples and Next Steps link cards, and updates the page tag to "AI".
threepointone
requested review from
elithrar,
irvinebroque,
rita3ko,
thomasgauvin and
whoiskatrin
as code owners
February 21, 2026 19:32
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
- authorization.mdx: remove orphaned <diagram> tag, fix broken anchor (#3 -> #2), fix "oAuth" -> "OAuth", add pcx_content_type, rewrite permission code to use correct MCP tool handler signature, replace MyMCPServer.Router with .serve(), remove unused DirectoryListing import - mcp-client-api.mdx: fix this.env bug in createMcpOAuthProvider (capture env before returning object literal), fix import path for error utils, remove dead code after return, replace OpenAI example with Workers AI - mcp-handler-api.mdx: fix misleading intro (stateless vs stateful, not SSE), fix storage.kv -> storage.get/put, fix {} as ExecutionContext, wrap global McpServer in factory function, fix "accessable" typo - remote-mcp-server.mdx: fix MyMCP.Router -> .serve(), fix Auth0/WorkOS anchors pointing to #stytch, fix https://localhost -> http://localhost, fix broken MCP client link - securing-mcp-server.mdx: fix apiHandlers -> apiRoute + apiHandler - test-remote-mcp-server.mdx: fix https -> http localhost, fix "lets you to test" typo, remove outdated claim about Claude Desktop - tools.mdx: add missing tags, add .js extension to import, remove unused Render import, fix stale repo link - governance.mdx: add pcx_content_type, remove empty import - index.mdx: fix http -> https links for Claude and Cursor - mcp-servers-for-cloudflare.mdx: fix "streamble-http" typo, remove unused Render import, fix link to source code -> docs - transport.mdx: remove unused Render/TabItem/Tabs imports - oauth-mcp-client.mdx: fix extends Agent -> Agent<Env> (5 instances) - connect-mcp-client.mdx: fix extends Agent -> Agent<Env> (3 instances) Co-authored-by: Cursor <cursoragent@cursor.com>
tools.mdx: Full rewrite from 36-line stub to comprehensive reference. Covers tool definitions, results, error handling, descriptions best practices, Zod input validation, and usage with both createMcpHandler and McpAgent. All examples use the factory function pattern. mcp-handler-api.mdx: Add missing State type definition in stateful example, fix onMcpRequest -> onRequest in Worker handler, remove unused Render import. authorization.mdx: Rewrite bottom half to show auth context usage for both McpAgent (this.props) and createMcpHandler (getMcpAuthContext), with proper type definitions. Clarify the two permission approaches (check inside handler vs conditional registration) and when to use each. Co-authored-by: Cursor <cursoragent@cursor.com>
threepointone
changed the title
whoiskatrin
approved these changes
Feb 21, 2026
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
6 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
A comprehensive pass over the Agents documentation: migrates examples to Workers AI, rewrites the landing page and several concept/reference pages, and fixes bugs across MCP docs.
Workers AI migration
Replaced
OPENAI_API_KEY/ OpenAI SDK references with Workers AI in pages where the provider was incidental to the feature being documented:index.mdx— Removed.env/ API key step from quickstart. The agents-starter now uses Workers AI by default.using-ai-models.mdx— Streaming example usesworkers-ai-provider+ AI SDK. AI SDK section leads with Workers AI, shows OpenAI as a swap. Fixed multiple code bugs (env.AI.run→this.env.AI.run, undefined variable, wrong Gemini model name, missing type params).store-and-sync-state.mdx— Model context example usesthis.env.AI.run().http-sse.mdx— SSE example usescreateWorkersAIinstead ofcreateOpenAI.browse-the-web.mdx— Browser scraping example usesthis.env.AI.run(), addedAIbinding to wrangler config.mcp-client-api.mdx— AI SDK integration example uses Workers AI instead ofopenai("gpt-4").Intentionally kept as OpenAI:
configuration.mdx(secrets management example),chat-agents.mdx(multi-provider comparison),slack-agent.mdx(full tutorial).Landing page rewrite (
index.mdx)AIChatAgentcalled outAgent(counter) andAIChatAgent(chat) code examplesPage rewrites
using-ai-models.mdx— Full rewrite. Clean intro, fixed all code bugs, Workers AI first throughout.calling-llms.mdx— Rewrote from thin 37-line generic page to patterns-focused content: state as context, surviving disconnections, autonomous model calls, multi-model pipelines, caching and cost control.agent-class.mdx— Fixed code bugs (ws.send(msg), missingnew, fakestorage.kv), cleaned up PartyKit references, added Layer 3:AIChatAgentsection.tools.mdx(MCP) — Full rewrite from 36-line stub to comprehensive reference covering tool definitions, results, error handling, descriptions, Zod validation, and usage with bothcreateMcpHandlerandMcpAgent.authorization.mdx(MCP) — Rewrote bottom half: auth context usage for bothMcpAgent(this.props) andcreateMcpHandler(getMcpAuthContext()), permission-based tool access with two approaches explained.MCP docs bug fixes (13 files)
authorization.mdx— Removed orphaned<diagram>tag, fixed broken anchor, fixed "oAuth" → "OAuth", addedpcx_content_type, replacedMyMCPServer.Routerwith.serve()mcp-client-api.mdx— Fixedthis.envbug increateMcpOAuthProvider, fixed import path for error utils, removed dead codemcp-handler-api.mdx— Fixed misleading intro (stateless vs stateful), fixedstorage.kv→storage.get/put, added missingStatetype, fixedonMcpRequest→onRequestremote-mcp-server.mdx— FixedMyMCP.Router→.serve(), fixed Auth0/WorkOS anchors pointing to#stytch, fixedhttps://localhost→http://localhostsecuring-mcp-server.mdx— FixedapiHandlers→apiRoute+apiHandlertest-remote-mcp-server.mdx— Fixed localhost protocol, typo, outdated claimindex.mdx,transport.mdx,governance.mdx,mcp-servers-for-cloudflare.mdx,tools.mdx,oauth-mcp-client.mdx,connect-mcp-client.mdx— HTTP → HTTPS links, "streamble-http" → "streamable-http", unused imports, missingpcx_content_type,extends Agent→Agent<Env>(8 instances)Formatting
Ran
prettieron all agents docs.Test plan
npm run checkto validate frontmatter and types@modelcontextprotocol/sdkAPI