git:20260805.87b9536 to git:20260820.cd23820

46 added, 205 removed. Audit A to A.

---

name: agents-sdk

- description: Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, chat applications, voice agents, or browser automation. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.

+ description: Build or debug stateful applications that specifically use Cloudflare's `agents` package, including Agent classes, routing, callable methods, synchronized state, scheduling, AIChatAgent, durable execution, or Agents SDK client hooks. Do not trigger for generic AI-agent design, the OpenAI Agents SDK, or ordinary Durable Object work that does not use the Cloudflare Agents SDK.

---

# Cloudflare Agents SDK

- Your knowledge of the Agents SDK may be outdated. **Prefer retrieval over pre-training** for any Agents SDK task.

- ## Retrieval Sources

- Cloudflare docs: https://developers.cloudflare.com/agents/

- | Topic | Docs URL | Use for |

- |-------|----------|---------|

- | Getting started | [Quick start](https://developers.cloudflare.com/agents/getting-started/quick-start/) | First agent, project setup |

- | Adding to existing project | [Add to existing project](https://developers.cloudflare.com/agents/getting-started/add-to-existing-project/) | Install into existing Workers app |

- | Configuration | [Configuration](https://developers.cloudflare.com/agents/api-reference/configuration/) | `wrangler.jsonc`, bindings, assets, deployment |

- | Agent class | [Agents API](https://developers.cloudflare.com/agents/api-reference/agents-api/) | Agent lifecycle, patterns, pitfalls |

- | State | [Store and sync state](https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/) | `setState`, `validateStateChange`, persistence |

- | Routing | [Routing](https://developers.cloudflare.com/agents/api-reference/routing/) | URL patterns, `routeAgentRequest` |

- | Callable methods | [Callable methods](https://developers.cloudflare.com/agents/api-reference/callable-methods/) | `@callable`, RPC, streaming, timeouts |

- | Scheduling | [Schedule tasks](https://developers.cloudflare.com/agents/api-reference/schedule-tasks/) | `schedule()`, `scheduleEvery()`, cron |

- | Workflows | [Run workflows](https://developers.cloudflare.com/agents/api-reference/run-workflows/) | `AgentWorkflow`, durable multi-step tasks |

- | HTTP/WebSockets | [WebSockets](https://developers.cloudflare.com/agents/api-reference/websockets/) | Lifecycle hooks, hibernation |

- | Chat agents | [Chat agents](https://developers.cloudflare.com/agents/api-reference/chat-agents/) | `AIChatAgent`, streaming, tools, persistence |

- | Client SDK | [Client SDK](https://developers.cloudflare.com/agents/api-reference/client-sdk/) | `useAgent`, `useAgentChat`, React hooks |

- | Client tools | [Client tools](https://developers.cloudflare.com/agents/api-reference/client-tools/) | Client-side tools, `autoContinueAfterToolResult` |

- | Server-driven messages | [Trigger patterns](https://developers.cloudflare.com/agents/api-reference/trigger-patterns/) | `saveMessages`, `waitUntilStable`, server-initiated turns |

- | Resumable streaming | [Resumable streaming](https://developers.cloudflare.com/agents/api-reference/resumable-streaming/) | Stream recovery on disconnect |

- | Email | [Email](https://developers.cloudflare.com/agents/api-reference/email/) | Email routing, secure reply resolver |

- | MCP client | [MCP client](https://developers.cloudflare.com/agents/api-reference/mcp-client-api/) | Connecting to MCP servers |

- | MCP server | [MCP server](https://developers.cloudflare.com/agents/api-reference/mcp-agent-api/) | Building MCP servers with `McpAgent` |

- | MCP transports | [MCP transports](https://developers.cloudflare.com/agents/api-reference/mcp-transports/) | Streamable HTTP, SSE, RPC transport options |

- | Securing MCP servers | [Securing MCP](https://developers.cloudflare.com/agents/api-reference/securing-mcp-servers/) | OAuth, proxy MCP, hardening |

- | Human-in-the-loop | [Human-in-the-loop](https://developers.cloudflare.com/agents/concepts/human-in-the-loop/) | Approval flows, `needsApproval`, workflows |

- | Durable execution | [Durable execution](https://developers.cloudflare.com/agents/api-reference/durable-execution/) | `runFiber()`, `stash()`, surviving DO eviction |

- | Queue | [Queue](https://developers.cloudflare.com/agents/api-reference/queue-tasks/) | Built-in FIFO queue, `queue()` |

- | Retries | [Retries](https://developers.cloudflare.com/agents/api-reference/retries/) | `this.retry()`, backoff/jitter |

- | Observability | [Observability](https://developers.cloudflare.com/agents/api-reference/observability/) | Diagnostics-channel events |

- | Push notifications | [Push notifications](https://developers.cloudflare.com/agents/api-reference/push-notifications/) | Web Push + VAPID from agents |

- | Webhooks | [Webhooks](https://developers.cloudflare.com/agents/api-reference/webhooks/) | Receiving external webhooks |

- | Cross-domain auth | [Cross-domain auth](https://developers.cloudflare.com/agents/api-reference/cross-domain-authentication/) | WebSocket auth, tokens, CORS |

- | Readonly connections | [Readonly](https://developers.cloudflare.com/agents/api-reference/readonly-connections/) | `shouldConnectionBeReadonly` |

- | Voice | [Voice](https://developers.cloudflare.com/agents/api-reference/voice/) | Experimental STT/TTS, `withVoice` |

- | Browse the web | [Browser tools](https://developers.cloudflare.com/agents/api-reference/browse-the-web/) | Experimental CDP browser automation |

- | Think | [Think](https://developers.cloudflare.com/agents/api-reference/think/) | Experimental higher-level chat agent class |

- | Migrations | [AI SDK v5](https://developers.cloudflare.com/agents/guides/migration-to-ai-sdk-v5/), [AI SDK v6](https://developers.cloudflare.com/agents/guides/migration-to-ai-sdk-v6/) | Upgrading `@cloudflare/ai-chat` |

- ## Capabilities

- The Agents SDK provides:

- - **Persistent state** — SQLite-backed, auto-synced to clients via `setState`

- - **Callable RPC** — `@callable()` methods invoked over WebSocket

- - **Scheduling** — One-time, recurring (`scheduleEvery`), and cron tasks

- - **Workflows** — Durable multi-step background processing via `AgentWorkflow`

- - **Durable execution** — `runFiber()` / `stash()` for work that survives DO eviction

- - **Queue** — Built-in FIFO queue with retries via `queue()`

- - **Retries** — `this.retry()` with exponential backoff and jitter

- - **MCP integration** — Connect to MCP servers or build your own with `McpAgent`

- - **Email handling** — Receive and reply to emails with secure routing

- - **Streaming chat** — `AIChatAgent` with resumable streams, message persistence, tools

- - **Server-driven messages** — `saveMessages`, `waitUntilStable` for proactive agent turns

- - **React hooks** — `useAgent`, `useAgentChat` for client apps

- - **Observability** — `diagnostics_channel` events for state, RPC, schedule, lifecycle

- - **Push notifications** — Web Push + VAPID delivery from agents

- - **Webhooks** — Receive and verify external webhooks

- - **Voice** (experimental) — STT/TTS via `@cloudflare/voice`

- - **Browser tools** (experimental) — CDP-powered browsing via `agents/browser`

- - **Think** (experimental) — Higher-level chat agent via `@cloudflare/think`

- ## FIRST: Verify Installation

- ```bash

- npm ls agents # Should show agents package

- ```

- If not installed:

- ```bash

- npm install agents

- ```

- For chat agents:

- ```bash

- npm install agents @cloudflare/ai-chat ai @ai-sdk/react

- ```

- ## Wrangler Configuration

- ```jsonc

- {

- "compatibility_flags": ["nodejs_compat"],

- "durable_objects": {

- "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]

- },

- "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]

- }

- ```

- **Gotchas:**

- - Do NOT enable `experimentalDecorators` in tsconfig (breaks `@callable`)

- - Never edit old migrations — always add new tags

- - Each agent class needs its own DO binding + migration entry

- - Add `"ai": { "binding": "AI" }` for Workers AI

- ## Agent Class

- ```typescript

- import { Agent, routeAgentRequest, callable } from "agents";

- type State = { count: number };

- export class Counter extends Agent<Env, State> {

- initialState = { count: 0 };

- validateStateChange(nextState: State, source: Connection | "server") {

- if (nextState.count < 0) throw new Error("Count cannot be negative");

- }

- onStateUpdate(state: State, source: Connection | "server") {

- console.log("State updated:", state);

- }

- @callable()

- increment() {

- this.setState({ count: this.state.count + 1 });

- return this.state.count;

- }

- export default {

- fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })

- };

- ```

- ## Routing

- Requests route to `/agents/{agent-name}/{instance-name}`:

- | Class | URL |

- |-------|-----|

- | `Counter` | `/agents/counter/user-123` |

- | `ChatRoom` | `/agents/chat-room/lobby` |

- Client: `useAgent({ agent: "Counter", name: "user-123" })`

- Custom routing: use `getAgentByName(env.MyAgent, "instance-id")` then `agent.fetch(request)`.

- ## Core APIs

- | Task | API |

- |------|-----|

- | Read state | `this.state.count` |

- | Write state | `this.setState({ count: 1 })` |

- | SQL query | `` this.sql`SELECT * FROM users WHERE id = ${id}` `` |

- | Schedule (delay) | `await this.schedule(60, "task", payload)` |

- | Schedule (cron) | `await this.schedule("0 * * * *", "task", payload)` |

- | Schedule (interval) | `await this.scheduleEvery(30, "poll")` |

- | RPC method | `@callable() myMethod() { ... }` |

- | Streaming RPC | `@callable({ streaming: true }) stream(res) { ... }` |

- | Start workflow | `await this.runWorkflow("ProcessingWorkflow", params)` |

- | Durable fiber | `await this.runFiber("name", async (ctx) => { ... })` |

- | Enqueue work | `this.queue("handler", payload)` |

- | Retry with backoff | `await this.retry(fn, { maxAttempts: 5 })` |

- | Broadcast to clients | `this.broadcast(message)` |

- | Get connections | `this.getConnections(tag?)` |

- ## React Client

+ Use current Cloudflare documentation and the installed `agents` package as the

+ contract. APIs in this SDK evolve quickly; do not trust remembered signatures or

+ examples without checking the relevant version.

- ```tsx

- import { useAgent } from "agents/react";

+ ## Inspect first

- function App() {

- const [state, setLocalState] = useState({ count: 0 });

+ 1. Read the project's package version, Wrangler configuration, Agent exports,

+ routing entrypoint, and generated binding types.

+ 2. Retrieve the current docs for the feature being changed.

+ 3. Inspect installed exports and `.d.ts` files before adding casts or adapters.

+ 4. Identify the Agent instance name and who is authorized to select it. Instance

+ naming is a state-partition and access-control decision, not just a URL detail.

- const agent = useAgent({

- agent: "Counter",

- name: "my-instance",

- onStateUpdate: (newState) => setLocalState(newState),

- onIdentity: (name, agentType) => console.log(`Connected to ${name}`)

- });

+ Agents require Durable Objects. Verify the exact class export, binding, and

+ lifecycle declaration used by the target environment. Do not copy a migration

+ or configuration example without checking the current lifecycle model.

- return (

- <button onClick={() => agent.setState({ count: state.count + 1 })}>

- Count: {state.count}

- </button>

- );

- }

- ```

+ ## Preserve the runtime contract

- ## References

+ - Treat persisted Agent state, connection state, scheduled work, and client UI

+ state as separate surfaces.

+ - Validate client-originated state and callable methods at the server boundary;

+ a callable method is not authorization by itself.

+ - Use stable operation identities for work that may be retried or resumed.

+ - Distinguish ordinary request work from SDK durable-execution primitives. Use

+ the latter only when work must survive Durable Object eviction or restart.

+ - Expect the Agent constructor and in-memory state to be recreated. Persist

+ anything required after eviction.

+ - Keep routing and client naming consistent. Test the actual route through

+ `routeAgentRequest` or the project's custom router.

+ - Treat experimental integrations as version-specific. Pin and test the seam

+ rather than spreading preview types through domain code.

- ### Core

- - **[references/state-scheduling.md](references/state-scheduling.md)** — State persistence, scheduling, SQL

- - **[references/callable.md](references/callable.md)** — RPC methods, streaming, timeouts

- - **[references/routing.md](references/routing.md)** — URL patterns, custom routing, `getAgentByName`

- - **[references/configuration.md](references/configuration.md)** — Wrangler config, bindings, Vite setup

+ ## Load only the relevant reference

- ### Chat & Streaming

- - **[references/streaming-chat.md](references/streaming-chat.md)** — AIChatAgent, resumable streams, tools

- - **[references/client-sdk.md](references/client-sdk.md)** — `useAgent`, `useAgentChat`, `AgentClient`

- - **[references/server-driven-messages.md](references/server-driven-messages.md)** — Trigger patterns, `saveMessages`

- - **[references/human-in-the-loop.md](references/human-in-the-loop.md)** — Approval flows, `needsApproval`

+ | Need | Reference |

+ | --- | --- |

+ | State, SQL, schedules, or alarms | [state-scheduling.md](references/state-scheduling.md) |

+ | Callable RPC, streaming, or timeouts | [callable.md](references/callable.md) |

+ | Routing, bindings, or project setup | [routing.md](references/routing.md), [configuration.md](references/configuration.md) |

+ | React/browser clients or chat streaming | [client-sdk.md](references/client-sdk.md), [streaming-chat.md](references/streaming-chat.md) |

+ | Server-driven turns or approval flows | [server-driven-messages.md](references/server-driven-messages.md), [human-in-the-loop.md](references/human-in-the-loop.md) |

+ | Workflows, fibers, queues, or retries | [workflows.md](references/workflows.md), [durable-execution.md](references/durable-execution.md), [queue-retries.md](references/queue-retries.md) |

+ | MCP, email, webhooks, push, or observability | [mcp.md](references/mcp.md), [email.md](references/email.md), [webhooks-push.md](references/webhooks-push.md), [observability.md](references/observability.md) |

+ | Preview features | [think.md](references/think.md), [voice.md](references/voice.md), [codemode.md](references/codemode.md), [browse-the-web.md](references/browse-the-web.md) |

- ### Background Processing

- - **[references/workflows.md](references/workflows.md)** — Durable Workflows integration

- - **[references/durable-execution.md](references/durable-execution.md)** — `runFiber`, `stash`, surviving eviction

- - **[references/queue-retries.md](references/queue-retries.md)** — Built-in queue, retry with backoff

+ Read current first-party docs before relying on limits, package names,

+ configuration fields, or experimental availability.

- ### Integrations

- - **[references/mcp.md](references/mcp.md)** — MCP client and server, transports, securing

- - **[references/email.md](references/email.md)** — Email routing and handling

- - **[references/webhooks-push.md](references/webhooks-push.md)** — Webhooks, push notifications

- - **[references/observability.md](references/observability.md)** — Diagnostics-channel events

+ ## Verify proportionally

- ### Experimental

- - **[references/think.md](references/think.md)** — `@cloudflare/think` higher-level chat agent

- - **[references/voice.md](references/voice.md)** — `@cloudflare/voice` STT/TTS

- - **[references/codemode.md](references/codemode.md)** — Code Mode for tool orchestration

- - **[references/browse-the-web.md](references/browse-the-web.md)** — CDP browser tools

+ Run the narrow type, route, and state tests for the changed seam. For connection

+ or recovery behavior, test disconnect/reconnect and a recreated Agent instance.

+ For scheduled or durable work, prove that duplicate delivery converges and that

+ the persisted result—not an in-memory flag—defines completion.