AGENTS.md@examples · git:20260207.c3211d0 · 2026-02-07 · sha256 c10988d09ba2a59f
AGENTS.md@examples git:20260207.c3211d0A

Name: AGENTS.md@examples
Author: pertamaxxx
Immutable. This exact content is served forever at /api/v1/blob/c10988d09ba2a59f.
# AGENTS.md — examples/

Self-contained demo apps that show how to use the Agents SDK. These are user-facing learning material — keep them simple, clear, and consistent.

Each example should focus on **one feature or concept** (e.g., MCP servers, email routing, workflows). The exception is `playground/`, which is the kitchen-sink showcase covering the full spread of SDK features in a single app.

## All examples are full-stack

Every example has both a frontend and a backend. This makes them immediately runnable and visually demonstrable — users can `npm run dev` and see the feature in action, not just read server logs.

All examples use the [Cloudflare Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/) for development and builds.

## Required structure

Every example must have:

```
example-name/
  package.json          # name, dependencies, scripts
  vite.config.ts        # must use @cloudflare/vite-plugin
  wrangler.jsonc        # Workers config (not .toml)
  tsconfig.json         # must extend ../../tsconfig.base.json
  index.html            # Vite entry point
  README.md             # What this example demonstrates, how to run it
  src/
    server.ts           # Worker entry point
    client.tsx          # React client entry
```

## Conventions

### wrangler.jsonc

- Use `wrangler.jsonc` (not `.toml`)
- `compatibility_date: "2026-01-28"`, `compatibility_flags: ["nodejs_compat"]`
- Full-stack apps with client routing: add `"assets": { "not_found_handling": "single-page-application" }`
- Do not set `"directory"` in assets — the Vite plugin handles this

### vite.config.ts

Every example must use both the React and Cloudflare Vite plugins:

```ts
import { cloudflare } from "@cloudflare/vite-plugin";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react(), cloudflare()]
});
```

### tsconfig.json

Extend the base config. Only add overrides when the example genuinely needs them (e.g., JSX for React examples):

```json
{
  "extends": "../../tsconfig.base.json"
}
```

### env.d.ts

Generated by `npx wrangler types`. Do not hand-edit. Regenerate when bindings change.

Examples using `worker-configuration.d.ts` instead should be migrated to `env.d.ts`.

### .env.example

If the example needs secrets (API keys, etc.), include a `.env.example` showing what keys are needed:

```
OPENAI_API_KEY=your-key-here
```

Never commit actual secrets. Prefer `.env` / `.env.example` over `.dev.vars` / `.dev.vars.example`.

### UI — Kumo + agents-ui

All examples use [Kumo](https://kumo-ui.com/) (`@cloudflare/kumo`) for components and `@cloudflare/agents-ui` for shared cross-example UI. **Always check agents-ui before building something custom** — if it handles connection status, theme toggling, or branding, use the package.

#### Kumo basics

- Use Kumo components (`Button`, `Input`, `Surface`, `Text`, `Badge`, `Empty`, etc.) instead of hand-rolled HTML
- Use `@phosphor-icons/react` for icons (Kumo's icon library)
- Use Kumo semantic color tokens (`text-kumo-default`, `bg-kumo-base`, `border-kumo-line`, etc.) instead of raw Tailwind colors
- Use the `data-mode` attribute for dark mode — no `dark:` Tailwind variants
- Set `data-theme="workers"` on `<html>` for the Cloudflare-branded color theme

#### CSS imports (in `src/styles.css`)

```css
@import "tailwindcss";
@import "@cloudflare/kumo/styles/tailwind";
@import "@cloudflare/agents-ui/theme/workers.css";
```

#### `@cloudflare/agents-ui` — required shared components

Every example should use these from `@cloudflare/agents-ui`:

- **`ThemeProvider`** (from `@cloudflare/agents-ui/hooks`) — wrap your app in `client.tsx`
- **`ConnectionIndicator`** — show WebSocket connection state in the header
- **`ModeToggle`** — light/dark/system toggle in the header
- **`PoweredByAgents`** — footer attribution badge (**required in every example**)

Don't re-implement connection indicators, theme toggles, or branding — import them.

See `/design/visuals.md` for detailed Kumo usage patterns and known gaps.

### Dependencies

- Keep example-specific dependencies minimal — these ship as learning material
- Shared dependencies (`react`, `vite`, `wrangler`, `@cloudflare/vite-plugin`, etc.) live in the root `package.json`
- Only add dependencies in the example's `package.json` if they're specific to what the example demonstrates

### README.md

Every example needs one. Keep it short:

1. One sentence: what this example demonstrates
2. How to run it (`npm install && npm run dev`)
3. Any required env vars
4. Link to relevant SDK docs in `/docs` if applicable

## Known issues to clean up

See `TODO.md` in this folder for the full checklist.

- Several examples are worker-only and need a frontend added: `email-agent/`, `mcp-elicitation/`, `mcp-server/`, `mcp-worker/`, `mcp-worker-authenticated/`, `x402/`, `x402-mcp/`
- `cross-domain/` has a `vite.config.ts` but does not use `@cloudflare/vite-plugin`
- `x402/` is missing README.md
- `x402/` and `x402-mcp/` use `worker-configuration.d.ts` instead of `env.d.ts`
- `codemode/` uses `.env.example` instead of `.dev.vars.example`
- Some full-stack examples set `assets.directory: "public"` — not needed with the Vite plugin