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 ```tsx import { useAgent } from "agents/react"; function App() { const [state, setLocalState] = useState({ count: 0 }); const agent = useAgent({ agent: "Counter", name: "my-instance", onStateUpdate: (newState) => setLocalState(newState), onIdentity: (name, agentType) => console.log(`Connected to ${name}`) }); return ( <button onClick={() => agent.setState({ count: state.count + 1 })}> Count: {state.count} </button> ); } ``` ## References ### 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 ### 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` ### Background Processing - **[references/workflows.md](references/workflows.md)** — Durable Workflows integration