Introduction to Cloudflare Agents

Build AI agents that persist, think, and act on Cloudflare’s global network

What are Cloudflare Agents?

Agents are persistent, stateful execution environments for agentic workloads, powered by Cloudflare Durable Objects. Each agent has its own state, storage, and lifecycle — with built-in support for real-time communication, scheduling, AI model calls, MCP, workflows, and more.

Agents hibernate when idle and wake on demand. You can run millions of them — one per user, per session, per game room — each costs nothing when inactive.

Why use Agents?

Persistent State

State syncs to all connected clients automatically and survives restarts, deploys, and hibernation. Stored in SQLite.

Real-time Sync

Built-in WebSocket support with real-time bidirectional communication and lifecycle hooks.

Global Network

Run on Cloudflare’s edge network, close to your users, with sub-50ms latency worldwide.

Zero Cost When Idle

Agents hibernate when no clients are connected. Wake on demand. Pay only for what you use.

Key Features

Callable Methods

Type-safe RPC via the @callable() decorator. Call agent methods like they’re local functions from your frontend.

@callable()
increment() {
  this.setState({ count: this.state.count + 1 });
  return this.state.count;
}

AI Chat

Message persistence, resumable streaming, and server/client tool execution for building AI chat experiences.

Scheduling

One-time, recurring, and cron-based tasks. Run background jobs at scale.

MCP (Model Context Protocol)

Act as MCP servers or connect as MCP clients to expose tools and resources.

Workflows

Durable multi-step tasks with human-in-the-loop approval.

Email

Receive and respond to emails via Cloudflare Email Routing.

React Hooks

useAgent and useAgentChat hooks for seamless frontend integration.

Quick Example

A counter agent with persistent state, callable methods, and real-time sync:

server.ts

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

export type CounterState = { count: number };

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

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }

  @callable()
  decrement() {
    this.setState({ count: this.state.count - 1 });
    return this.state.count;
  }
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return (
      (await routeAgentRequest(request, env)) ??
      new Response("Not found", { status: 404 })
    );
  }
};

State changes sync to all connected clients automatically. Call methods like they’re local functions.

Get Started

Quick Start

Build your first agent in 10 minutes with our step-by-step guide.

Add to Existing Project

Integrate agents into your existing Cloudflare Workers application.

Coming Soon

Realtime Voice

Voice agents with real-time audio processing

Web Browsing

Headless browser automation

Sandboxed Code

Safe execution of user-generated code