agents-sdk

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, or chat applications. Covers Agent class, state management, callable RPC, Workflows integration, and React hooks.

Cloudflare Agents SDK

Not to be confused with the OpenAI Agents SDK (Python-based agent orchestration). This skill covers Cloudflare's Agents SDK for building stateful agents on Workers.

Prefer retrieval over pre-training — the Agents SDK evolves rapidly. Current version: v0.14.0 (June 2, 2026).

Documentation

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

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), cron, and declarative scheduled tasks (v0.14+)
• Workflows - Durable multi-step background processing via AgentWorkflow, with reasoning steps (v0.14+)
• 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 and hardened recovery (v0.14+)
• Agent Skills - Modular, composable skill definitions (v0.14+)
• Chat Messengers - Direct Telegram integration (v0.14+)
• 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}:

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

Core APIs

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)