agents-sdk

✓Verified·Scanned 2/18/2026

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.

by cloudflare·vfe4f2e9·31.3 KB·704 installs

Scanned from main at fe4f2e9 · Transparency log ↗

$ vett add cloudflare/skills/agents-sdk

Cloudflare Agents SDK

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

Documentation

Fetch current docs from https://github.com/cloudflare/agents/tree/main/docs before implementing.

Topic	Doc	Use for
Getting started	`docs/getting-started.md`	First agent, project setup
State	`docs/state.md`	`setState`, `validateStateChange`, persistence
Routing	`docs/routing.md`	URL patterns, `routeAgentRequest`, `basePath`
Callable methods	`docs/callable-methods.md`	`@callable`, RPC, streaming, timeouts
Scheduling	`docs/scheduling.md`	`schedule()`, `scheduleEvery()`, cron
Workflows	`docs/workflows.md`	`AgentWorkflow`, durable multi-step tasks
HTTP/WebSockets	`docs/http-websockets.md`	Lifecycle hooks, hibernation
Email	`docs/email.md`	Email routing, secure reply resolver
MCP client	`docs/mcp-client.md`	Connecting to MCP servers
MCP server	`docs/mcp-servers.md`	Building MCP servers with `McpAgent`
Client SDK	`docs/client-sdk.md`	`useAgent`, `useAgentChat`, React hooks
Human-in-the-loop	`docs/human-in-the-loop.md`	Approval flows, pausing workflows
Resumable streaming	`docs/resumable-streaming.md`	Stream recovery on disconnect

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

Capabilities

The Agents SDK provides:

Persistent state - SQLite-backed, auto-synced to clients
Callable RPC - @callable() methods invoked over WebSocket
Scheduling - One-time, recurring (scheduleEvery), and cron tasks
Workflows - Durable multi-step background processing via AgentWorkflow
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
React hooks - useAgent, useAgentChat for client apps

FIRST: Verify Installation

npm ls agents  # Should show agents package

If not installed:

npm install agents

Wrangler Configuration

{
  "durable_objects": {
    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}

Agent Class

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

type State = { count: number };

export class Counter extends Agent<Env, State> {
  initialState = { count: 0 };

  // Validation hook - runs before state persists (sync, throwing rejects the update)
  validateStateChange(nextState: State, source: Connection | "server") {
    if (nextState.count < 0) throw new Error("Count cannot be negative");
  }

  // Notification hook - runs after state persists (async, non-blocking)
  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" })

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)`

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

References

references/workflows.md - Durable Workflows integration
references/callable.md - RPC methods, streaming, timeouts
references/state-scheduling.md - State persistence, scheduling
references/streaming-chat.md - AIChatAgent, resumable streams
references/mcp.md - MCP server integration
references/email.md - Email routing and handling
references/codemode.md - Code Mode (experimental)