Skip to content

Updated 4 Agents guides to latest#28319

Open
ask-bonk[bot] wants to merge 4 commits intoproductionfrom
opencode/issue28318-20260213130327
Open

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

Conversation

@ask-bonk
Copy link
Contributor

@ask-bonk ask-bonk bot commented Feb 13, 2026

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

@opencode-agent
[Agents] Update getting-started guides to align with latest best prac…
a44e77f 
…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
@ask-bonk ask-bonk bot mentioned this pull request Feb 13, 2026
Closed
@github-actions 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
Copy link
Contributor

github-actions bot commented Feb 13, 2026

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
Copy link
Collaborator

elithrar commented Feb 13, 2026

/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
Copy link
Contributor

github-actions bot commented Feb 13, 2026 •
edited
Loading

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/

@opencode-agent
[Agents] Fix structural inconsistencies across getting-started guides
6f15e6e 
- 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
Copy link
Contributor Author

ask-bonk bot commented Feb 13, 2026

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
Copy link
Collaborator

elithrar commented Feb 13, 2026

/bonk fix the CI failure

@ask-bonk
Copy link
Contributor Author

ask-bonk bot commented Feb 13, 2026

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

@opencode-agent
[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>.
@ask-bonk
Copy link
Contributor Author

ask-bonk bot commented Feb 13, 2026

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

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

  1. 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.

  2. 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

@vygnqq5nx9-lgtm vygnqq5nx9-lgtm mentioned this pull request Feb 15, 2026
Open
@threepointone
Copy link
Contributor

threepointone commented Feb 16, 2026

I incorporated all the changes from here into #28378 so I can drop them all at once. Except for the testing doc. I need to really rethink and rewrite that one.

@ask-bonk ask-bonk bot mentioned this pull request Feb 18, 2026
Merged
@github-actions
Copy link
Contributor

github-actions bot commented Mar 3, 2026

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label is helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).

@github-actions github-actions bot added the stale label Mar 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@threepointone threepointone threepointone left review comments

@irvinebroque irvinebroque irvinebroque approved these changes

@rita3ko rita3ko Awaiting requested review from rita3ko rita3ko is a code owner

@elithrar elithrar Awaiting requested review from elithrar elithrar is a code owner

@thomasgauvin thomasgauvin Awaiting requested review from thomasgauvin thomasgauvin is a code owner

@whoiskatrin whoiskatrin Awaiting requested review from whoiskatrin whoiskatrin is a code owner

Assignees

@elithrar elithrar

@threepointone threepointone

@irvinebroque irvinebroque

@rita3ko rita3ko

@whoiskatrin whoiskatrin

@thomasgauvin thomasgauvin

Labels

product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. size/m stale

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

update agents starters

6 participants

@elithrar @threepointone @irvinebroque @rita3ko @whoiskatrin @thomasgauvin