Updated 4 Agents guides to latest by ask-bonk[bot] · Pull Request #28319 · cloudflare/cloudflare-docs

ask-bonk · 2026-02-13T13:10:03Z

All changes are committed. Here is a summary of all updates made across the four guides:

Changes by file

quick-start.mdx

Updated compatibility_date from "2025-01-01" to "$today" per Workers best practices
Added satisfies ExportedHandler<Env> to the default export

add-to-existing-project.mdx

Updated compatibility_date from "2025-01-01" to "$today"
Added @callable() decorators to the CounterAgent example (was missing, inconsistent with quick-start)
Added satisfies ExportedHandler<Env> to all five default export examples (plain Workers, static assets, auth, server access)
Replaced manual Env interface typing guidance with wrangler types generation guidance per best practices

testing-your-agent.mdx

Fixed vitest config file references from .js to .ts (matches the actual starter)
Fixed code block language from js to ts for vitest config examples
Removed $ prefix from terminal commands (npm run test, npx vitest, npx wrangler dev)
Changed sh output code blocks to txt (unsupported language identifier)

build-a-chat-agent.mdx

Updated AIChatAgent import from "agents/ai-chat-agent" to "@cloudflare/ai-chat" (matches current starter)
Added proper onChatMessage type signature with StreamTextOnFinishCallback<ToolSet>
Updated tool definitions from parameters to inputSchema (AI SDK v5 API)
Updated zod import from "zod" to "zod/v3" (matches current starter)
Updated unstable_getSchedulePrompt to getSchedulePrompt from "agents/schedule"
Changed .dev.vars to .env for local secrets per Workers best practices
Added .gitignore reminder for .env files
Added wrangler secret bulk .env guidance for uploading secrets to production
Removed outdated "npm run dev not found" troubleshooting entry
Updated server URL troubleshooting to be generic (URL may vary)

Closes #28318

github run

@callable

…tices and agents-starter - Use $today for compatibility_date per Workers best practices - Update AIChatAgent import to @cloudflare/ai-chat - Update tool definitions to use inputSchema (AI SDK v5) and zod/v3 - Update getSchedulePrompt import to agents/schedule - Add satisfies ExportedHandler<Env> to all default exports - Replace .dev.vars with .env for local secrets per best practices - Add wrangler secret bulk .env guidance for production - Replace hand-written Env types with wrangler types guidance - Add @callable() decorators to add-to-existing-project example - Fix vitest config references from .js to .ts - Remove $ prefix from terminal commands in testing guide - Use txt language for command output blocks

github-actions · 2026-02-13T13:11:07Z

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
`/src/content/docs/agents/`	`@irvinebroque`, `@rita3ko`, `@elithrar`, `@thomasgauvin`, `@threepointone`, `@whoiskatrin`, `@cloudflare/pcx-technical-writing`, `@cloudflare/ai-agents`, `@cloudflare/dev-plat-leads`

elithrar · 2026-02-13T13:22:41Z

/bonk great. re-review, and suggest any structural improvements that make sure each of these guides is consistent, clear about the goals, and easy to understand for new users to Agents. assume 90% of users who read this are earlier career and/or new to Workers and the Agents SDK.

avoid over-explaining or diluting the guide itself, but look for ambiguity in instructions and correct for it.

github-actions · 2026-02-13T13:24:32Z

Preview URL: https://00f5e91c.preview.developers.cloudflare.com
Preview Branch URL: https://opencode-issue28318-20260213130327.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/agents/getting-started/build-a-chat-agent/	https://opencode-issue28318-20260213130327.preview.developers.cloudflare.com/agents/getting-started/build-a-chat-agent/
https://developers.cloudflare.com/agents/getting-started/testing-your-agent/	https://opencode-issue28318-20260213130327.preview.developers.cloudflare.com/agents/getting-started/testing-your-agent/
https://developers.cloudflare.com/agents/getting-started/add-to-existing-project/	https://opencode-issue28318-20260213130327.preview.developers.cloudflare.com/agents/getting-started/add-to-existing-project/
https://developers.cloudflare.com/agents/getting-started/quick-start/	https://opencode-issue28318-20260213130327.preview.developers.cloudflare.com/agents/getting-started/quick-start/

- quick-start: add project name to create command so cd my-agent matches - add-to-existing-project: add missing description, fix misdirected 'starting fresh' link to point to quick-start instead of chat agent, add missing Agent import in multiple-agents example - testing-your-agent: add missing description, fix pcx_content_type to how-to, fix response.text() to response.json() in test examples, use relative URL for wrangler dev link, add Next steps section - build-a-chat-agent: rename Step 3 to 'Run the dev server' to avoid confusion with testing guide, remove duplicate secrets section, add Next steps section, import LinkCard

ask-bonk · 2026-02-13T13:27:52Z

Here is a summary of what I found and fixed:

Structural review summary

Issues found and fixed

quick-start.mdx

The npm create cloudflare@latest command did not pass a project name, but the next instruction said cd my-agent. Added my-agent as the project name argument so these match.

add-to-existing-project.mdx

Missing description in frontmatter. Added one.
Misdirected link: "If you are starting fresh, refer to Building a chat agent" pointed to the tutorial (sidebar order 4) instead of the Quick start (sidebar order 1). A new user starting fresh should go to the quick start. Fixed.
Missing Agent import: The "Adding multiple agents" section showed extends Agent but never imported it, and used the bare Agent type without <Env>. Fixed both.

testing-your-agent.mdx

Missing description in frontmatter. Added one.
Wrong pcx_content_type: Was get-started but this is a how-to guide (explains how to set up and run tests, not a "start here" guide). Changed to how-to.
Bug in test code: Both test examples used response.text() with .toMatchObject(). response.text() returns a string, but toMatchObject expects an object. Changed to response.json().
External URL: Used full https://developers.cloudflare.com/workers/wrangler/commands/#dev URL instead of relative /workers/wrangler/commands/#dev. Fixed.
No "Next steps" section: Every other guide ends with Next steps / LinkCards. Added one linking to the chat agent tutorial, Vitest integration docs, and local development docs.

build-a-chat-agent.mdx

Confusing step name: "Step 3: Test the agent locally" is not about testing (there is a separate testing guide) — it is about running the dev server. Renamed to "Step 3: Run the dev server".
Duplicate secrets section: Step 2 already explains both .env and wrangler secret put/bulk. The "Environment variables in production" section under Deploy repeated the exact same commands. Removed the duplicate and added a back-reference to Step 2.
No "Next steps" section: Ended abruptly after troubleshooting. Added LinkCards for testing, scheduling, state management, and MCP servers.

Consistency improvements across all guides

Aspect	Before	After
Frontmatter `description`	2 of 4 had it	All 4 have it
"Next steps" section	2 of 4 had it	All 4 have it
Internal links use relative paths	3 of 4	All 4
Cross-guide references point to correct targets	"Starting fresh" pointed to tutorial	Points to quick-start
Code examples have correct assertions	`response.text()` + `toMatchObject`	`response.json()` + `toMatchObject`

github run

elithrar · 2026-02-13T21:09:28Z

/bonk fix the CI failure

ask-bonk · 2026-02-13T21:11:57Z

Fixed. The CI failure was caused by a broken link in testing-your-agent.mdx:177 — the LinkCard pointed to /workers/testing/local-development/ which doesn't exist. Changed it to /workers/development-testing/, which is the correct path for the Workers local development docs.

github run

threepointone · 2026-02-13T21:21:32Z

src/content/docs/agents/getting-started/add-to-existing-project.mdx

-export class Chat extends Agent {
+import { Agent } from "agents";
+
+export class Chat extends Agent<Env> {


we actually don't recommend adding Env because we default to Cloudflare.Env, which wrangler types generates

/bonk address this comment here re: wrangler types auto generation of Env and Agent<T> using it by default

src/content/docs/agents/getting-started/build-a-chat-agent.mdx

wrangler types generates Cloudflare.Env which Agent uses by default, so Agent<Env> is redundant. Keep Env only where a second type param (state) is needed, e.g. Agent<Env, CounterState>.

ask-bonk · 2026-02-13T21:52:18Z

Done. Here's what I changed to address @threepointone's review comment:

add-to-existing-project.mdx — two changes:

Lines 292, 299: Removed <Env> from Agent<Env> in the "Adding multiple agents" section. Since wrangler types generates Cloudflare.Env and Agent defaults to using it, extends Agent is sufficient when there's no state type parameter.
Line 226: Added a sentence to the "Generate TypeScript types" section explaining that Agent defaults to the generated Env type, so you only need to pass it explicitly when providing a second type parameter for state (e.g., Agent<Env, CounterState>).

I left Agent<Env, CounterState> as-is in the CounterAgent examples (both in this file and quick-start.mdx) because Env is required there to pass the state type as the second generic parameter.

github run

ask-bonk bot requested review from a team, elithrar, irvinebroque, rita3ko, thomasgauvin, threepointone and whoiskatrin as code owners February 13, 2026 13:10

ask-bonk bot mentioned this pull request Feb 13, 2026

update agents starters #28318

Open

github-actions bot added product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. size/m labels Feb 13, 2026

github-actions bot assigned elithrar, irvinebroque, rita3ko, thomasgauvin, threepointone and whoiskatrin Feb 13, 2026

fix: correct invalid link to local development docs

3425616

threepointone reviewed Feb 13, 2026

View reviewed changes

src/content/docs/agents/getting-started/build-a-chat-agent.mdx Show resolved Hide resolved

[Agents] Drop explicit <Env> from Agent where it is the default

00f5e91

wrangler types generates Cloudflare.Env which Agent uses by default, so Agent<Env> is redundant. Keep Env only where a second type param (state) is needed, e.g. Agent<Env, CounterState>.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated 4 Agents guides to latest#28319

Updated 4 Agents guides to latest#28319
ask-bonk[bot] wants to merge 4 commits intoproductionfrom
opencode/issue28318-20260213130327

ask-bonk bot commented Feb 13, 2026

Uh oh!

github-actions bot commented Feb 13, 2026

Uh oh!

elithrar commented Feb 13, 2026

Uh oh!

github-actions bot commented Feb 13, 2026 •

edited

Loading

Uh oh!

ask-bonk bot commented Feb 13, 2026

Uh oh!

elithrar commented Feb 13, 2026

Uh oh!

ask-bonk bot commented Feb 13, 2026

Uh oh!

threepointone Feb 13, 2026

Uh oh!

elithrar Feb 13, 2026

Uh oh!

Uh oh!

ask-bonk bot commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

ask-bonk bot commented Feb 13, 2026

Changes by file

Uh oh!

github-actions bot commented Feb 13, 2026

Uh oh!

elithrar commented Feb 13, 2026

Uh oh!

github-actions bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ask-bonk bot commented Feb 13, 2026

Structural review summary

Issues found and fixed

Consistency improvements across all guides

Uh oh!

elithrar commented Feb 13, 2026

Uh oh!

ask-bonk bot commented Feb 13, 2026

Uh oh!

threepointone Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

elithrar Feb 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ask-bonk bot commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

github-actions bot commented Feb 13, 2026 •

edited

Loading