AGENTS.md

AGENTS.md — guides/

In-depth, pattern-oriented tutorials — runnable apps with substantial narrative READMEs that teach how to build a particular kind of agent application.

How guides differ from examples

	Examples (/examples)	Guides (/guides)
Focus	One SDK feature or concept	A pattern or workflow spanning multiple features
README	Short — what it does, how to run it	Walkthrough — architecture, code explanations, best practices
Reader's goal	"Show me what this looks like"	"Teach me how to build this kind of app"

If it demonstrates a single feature, it belongs in /examples. If it teaches an approach or pattern, it belongs here.

Structure

Guides are runnable apps with the same structural conventions as examples:

guide-name/
  package.json
  vite.config.ts        # must use @cloudflare/vite-plugin
  wrangler.jsonc        # not .toml
  tsconfig.json         # must extend agents/tsconfig
  index.html
  src/
    server.ts
    client.tsx
  README.md             # the main artifact — this is the tutorial

The README is the guide. The code is the supporting material.

README expectations

A guide README should walk a reader through the application, explaining both what the code does and why it is structured that way. Cover:

1. What this guide teaches — the pattern or concept, with context (link to prior art, research, etc.)
2. Architecture overview — how the pieces fit together, what components are involved
3. Code walkthrough — key sections of code with explanations, not just the full source dumped in
4. How to run it — setup, env vars, pnpm run dev
5. Best practices — pitfalls, recommendations, what to do in production

Keep it narrative. The reader should be able to follow the README top-to-bottom and understand the pattern without reading every line of source code.

Conventions

• Follow the same Vite, wrangler, and tsconfig conventions as /examples (see /examples/AGENTS.md)
• Use .env.example for secrets
• compatibility_date: "2026-06-11", compatibility_flags: ["nodejs_compat"]

Current guides

Guide	Pattern
anthropic-patterns/	Five agent patterns from Anthropic's research (chaining, routing, parallelisation, orchestrator-workers, evaluator-optimizer)
human-in-the-loop/	AI agents that request human approval before executing actions

Known issues

• anthropic-patterns/ uses wrangler.json — should be wrangler.jsonc
• human-in-the-loop/ uses wrangler.toml — should be wrangler.jsonc