agents-sdk

by Cloudflare

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, or chat applications. Covers Agent class, state management, callable RPC, Workflows integration, and React hooks. npx skills add https://github.com/cloudflare/skills --skill agents-sdk Download ZIPGitHub2k

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 First agent, project setup Adding to existing project Add to existing project Install into existing Workers app Configuration Configuration wrangler.jsonc, bindings, assets, deployment Agent class Agents API Agent lifecycle, patterns, pitfalls State Store and sync state setState, validateStateChange, persistence Routing Routing URL patterns, routeAgentRequest Callable methods Callable methods @callable, RPC, streaming, timeouts Scheduling Schedule tasks schedule(), scheduleEvery(), cron Workflows Run workflows AgentWorkflow, durable multi-step tasks HTTP/WebSockets WebSockets Lifecycle hooks, hibernation Chat agents Chat agents AIChatAgent, streaming, tools, persistence Client SDK Client SDK useAgent, useAgentChat, React hooks Client tools Client tools Client-side tools, autoContinueAfterToolResult Server-driven messages Trigger patterns saveMessages, waitUntilStable, server-initiated turns Resumable streaming Resumable streaming Stream recovery on disconnect Email Email Email routing, secure reply resolver MCP client MCP client Connecting to MCP servers MCP server MCP server Building MCP servers with McpAgent MCP transports MCP transports Streamable HTTP, SSE, RPC transport options Securing MCP servers Securing MCP OAuth, proxy MCP, hardening Human-in-the-loop Human-in-the-loop Approval flows, needsApproval, workflows Durable execution Durable execution runFiber(), stash(), surviving DO eviction Queue Queue Built-in FIFO queue, queue() Retries Retries this.retry(), backoff/jitter Observability Observability Diagnostics-channel events Push notifications Push notifications Web Push + VAPID from agents Webhooks Webhooks Receiving external webhooks Cross-domain auth Cross-domain auth WebSocket auth, tokens, CORS Readonly connections Readonly shouldConnectionBeReadonly Voice Voice Experimental STT/TTS, withVoice Browse the web Browser tools Experimental CDP browser automation Think Think Experimental higher-level chat agent class Migrations AI SDK v5, 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

Agent Class

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

type State = { count: number };

export class Counter extends Agent {
 initialState = { count: 0 };

 validateStateChange(nextState: State, source: Connection | "server") {
 if (nextState.count 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.sqlSELECT * 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

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 (
 agent.setState({ count: state.count + 1 })}>
 Count: {state.count}
 
 );
}

References

Core

• references/state-scheduling.md — State persistence, scheduling, SQL

• references/callable.md — RPC methods, streaming, timeouts

• references/routing.md — URL patterns, custom routing, getAgentByName

• references/configuration.md — Wrangler config, bindings, Vite setup

Chat & Streaming

• references/streaming-chat.md — AIChatAgent, resumable streams, tools

• references/client-sdk.md — useAgent, useAgentChat, AgentClient

• references/server-driven-messages.md — Trigger patterns, saveMessages

• references/human-in-the-loop.md — Approval flows, needsApproval

Background Processing

• references/workflows.md — Durable Workflows integration

• references/durable-execution.md — runFiber, stash, surviving eviction

• references/queue-retries.md — Built-in queue, retry with backoff

Integrations

• references/mcp.md — MCP client and server, transports, securing

• references/email.md — Email routing and handling

• references/webhooks-push.md — Webhooks, push notifications

• references/observability.md — Diagnostics-channel events

Experimental

• references/think.md — @cloudflare/think higher-level chat agent

• references/voice.md — @cloudflare/voice STT/TTS

• references/codemode.md — Code Mode for tool orchestration

• references/browse-the-web.md — CDP browser tools