What Is the Cloudflare Agents SDK? The Durable Objects Guide

The Cloudflare Agents SDK makes one agent equal one stateful Durable Object. Here is the full runtime model, the class hierarchy, and when to choose it over a server-based engine.

What is the Cloudflare Agents SDK?

The Cloudflare Agents SDK is a TypeScript framework where every AI agent runs as a single, stateful Durable Object — a globally addressable micro-server with its own embedded SQLite database, its own WebSocket connections, and its own scheduler. You install it with npm i agents, subclass the Agent class, and deploy to Cloudflare Workers. The defining idea is that the agent is not a stateless function talking to a remote database; the agent is the database, the compute, and the scheduler fused into one addressable unit.

That fusion is what makes the Cloudflare Agents SDK different from almost every other agent runtime in 2026. In a conventional stack, an agent is a request handler: it boots cold, loads conversation state from Postgres or Redis, does some work, writes state back, and dies. Durability is something you assemble from external services. On Cloudflare, durability is the unit of compute itself. Each instance keeps its memory between requests, hibernates when idle without charging you for compute, and wakes up exactly where it left off.

The phrase to internalize is one agent = one Durable Object. If you are running a customer-support agent, you get one Durable Object per conversation. If you are running a research agent per user, you get one Durable Object per user. Each instance is single-threaded, isolated, and addressed by a stable name, so the same name always resolves to the same agent with its state intact. This is the framing the rest of this guide builds on, and it is the lens you need to decide whether Cloudflare is the right home for your agent.

What is a Cloudflare AI agent durable object, and why does it matter?

A Cloudflare AI agent durable object is a stateful, single-threaded micro-server that co-locates the agent’s compute with its own SQLite storage and scheduler, eliminating the network round-trips and race conditions that plague stateless agent runtimes. Because reads and writes happen against an embedded database in the same thread, they do not pay a network hop the way a stateless function hitting a regional database does.

Three properties of the cloudflare durable objects ai agent model do the heavy lifting. First, state co-location: the agent’s data lives next to its code, so a SQL read is effectively a local function call rather than a database query over the wire. Second, single-threaded correctness: each Durable Object processes one input at a time with gated I/O, so read-modify-write races simply cannot happen — you get correctness by construction without distributed locks. Third, hibernation economics: an idle agent is evicted from memory after roughly 70–140 seconds and stops accruing compute cost, while its WebSocket connections survive on Cloudflare’s network via the Hibernation API.

That last property is the quiet superpower. It means running one instance per user is economical at scale, because a million idle agents cost almost nothing in compute. You pay for storage and for the moments an agent is actually doing work. SQLite-backed Durable Objects are even available on the Workers Free plan, so you can prototype the full model before spending a cent on storage, which Cloudflare only began billing for in January 2026.

Cloudflare agent class internals: the DurableObject > Server > Agent > AIChatAgent hierarchy

The cloudflare agent class internals form a four-layer inheritance chain: DurableObject is the foundation, Server (from partyserver) adds developer-friendly callbacks, Agent adds state, scheduling and MCP, and AIChatAgent adds conversational message handling. The Agent class does not extend DurableObject directly — it extends Server, which extends DurableObject. Reading the hierarchy top to bottom is the fastest way to understand what you actually get.

Picture the stack as four concentric rings. The innermost ring, DurableObject, gives you globally addressable single-threaded compute with KV plus SQLite storage and native WebSocket and alarm support — the raw primitive. The next ring, Server (from the partyserver package), replaces those low-level primitives with ergonomic lifecycle callbacks: onStart, onRequest, and onConnect. The third ring, Agent, is where the framework earns its name — it layers on automatic state persistence, a managed scheduling system, task queues, email handling, AsyncLocalStorage context propagation, and an outbound MCP client. The outermost ring, AIChatAgent, specializes Agent for chat with an onChatMessage() hook, automatic message persistence to SQLite, and resumable streaming so a dropped connection can pick the response back up.

What does the Agent ring give you concretely? this.setState() persists JSON-serializable state to SQL and broadcasts it to every connected client over WebSocket via cf_agent_state messages. this.sql is a tagged-template query API against the embedded SQLite for anything bigger or more queryable than that small synced state. this.schedule() registers one-time, delayed, or cron tasks; because a Durable Object only has a single alarm, Agent stores every schedule in a built-in cf_agents_schedules table and multiplexes them through that one alarm. this.queue() defers work to a cf_agents_queues table that flushes sequentially. And this.mcp lets the agent act as a client to external Model Context Protocol servers over HTTP or RPC.

Agent vs AIChatAgent in Cloudflare: which class should you extend?

Extend Agent for any stateful background or task-oriented agent; extend AIChatAgent only when you are building a chat interface that needs message history, multi-turn persistence, and resumable streaming. AIChatAgent is a convenience layer, not a different runtime — under the hood it is still a Durable Object with all of Agent’s scheduling and SQL capabilities, plus opinionated plumbing for conversations.

The agent vs aichatagent cloudflare decision comes down to whether your workload is fundamentally a conversation. A document-processing agent, a cron-driven monitoring agent, an email triage agent, or an autonomous research worker should extend Agent — they have state and schedules but no chat transcript to manage. A copilot, a support bot, or any product where the user sees a streaming message thread should extend AIChatAgent, because you get the onChatMessage() hook, automatic persistence of every message to SQLite, and stream recovery so a flaky mobile connection does not lose a half-generated answer.

A practical tell: if you find yourself hand-rolling a messages table inside an Agent subclass and reimplementing streaming resumption, you wanted AIChatAgent all along. Conversely, if you extend AIChatAgent for a non-chat workload, you carry conversational machinery you never use. Choose by the shape of the interaction, not by whether an LLM is involved — both classes happily call models.

How do you build an AI agent on Cloudflare? A minimal Agent subclass

To build an AI agent on Cloudflare, scaffold the starter, subclass Agent, define your SQL schema in onStart, and wire a Durable Object binding with a new_sqlite_classes migration in wrangler.jsonc. The fastest start is the official template, which gives you the agent code, a React client, and a correctly configured wrangler file:

The starter command is npm create cloudflare@latest -- --template cloudflare/agents-starter. It produces src/server.ts (your agent), src/client.tsx (the frontend), and a wrangler.jsonc already set up with the Durable Object binding and SQLite migration. Below is the minimal shape of an Agent subclass that creates a schedules-backed reminder table and uses the built-in this.schedule() to fire a callback later — note how the SQL schema and the scheduling both live inside the same instance.

The configuration half matters just as much as the code. Agents require a Durable Object binding, and because they store state in SQLite, the class must be registered under new_sqlite_classes in a migration — not the older new_classes. You also need a recent compatibility_date (for example 2026-01-28) and, in most real projects, the nodejs_compat flag. Get the migration type wrong and your agent will appear to lose its memory on every request, because it never got a SQLite backend to persist to.

import { Agent, routeAgentRequest } from "agents";

interface Env {
  MyAgent: DurableObjectNamespace;
}

interface State {
  remindersSent: number;
}

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

  // Runs once when the instance first wakes; create co-located schema here.
  async onStart() {
    this.sql`
      CREATE TABLE IF NOT EXISTS reminders (
        id    TEXT PRIMARY KEY,
        topic TEXT NOT NULL,
        due   INTEGER NOT NULL
      )`;
  }

  // Public method a client calls to queue a reminder.
  async addReminder(topic: string, delaySeconds: number) {
    const id = crypto.randomUUID();
    this.sql`INSERT INTO reminders (id, topic, due)
             VALUES (${id}, ${topic}, ${Date.now() + delaySeconds * 1000})`;
    // schedule() persists to cf_agents_schedules and fires sendReminder().
    await this.schedule(delaySeconds, "sendReminder", { id, topic });
  }

  // The scheduled callback — runs even after the agent hibernated.
  async sendReminder(payload: { id: string; topic: string }) {
    // ...deliver the reminder (email, webhook, push)...
    this.setState({ remindersSent: this.state.remindersSent + 1 });
    this.sql`DELETE FROM reminders WHERE id = ${payload.id}`;
  }
}

export default {
  async fetch(request: Request, env: Env) {
    // Routes /agents/:name to a stable, named instance.
    return (await routeAgentRequest(request, env)) ??
      new Response("Not found", { status: 404 });
  },
};

What does Project Think add? Durable-execution fibers for long-running agents

Project Think, announced April 15, 2026, extends the Cloudflare Agents SDK with durable-execution fibers — runFiber, stash, and an onFiberRecovered hook — so an agent’s work survives eviction and hibernation and resumes from its last checkpoint after a platform restart. It is the cloudflare project think durable agents story end to end: a fiber is a durable function invocation that is registered in SQLite before it begins, checkpointable mid-flight, and recoverable on restart.

Here is the problem fibers solve. A multi-turn agent loop or a 30-second LLM call can outlive the moments an agent stays resident in memory. Before Project Think, the SDK shipped keepAlive() in March 2026 — an experimental heartbeat that holds an agent active for minutes-long work. Fibers go further: instead of merely staying awake, the agent records its progress so it can be evicted and brought back. You wrap durable work in runFiber(); you checkpoint state at safe points with ctx.stash(); and if the platform restarts the instance mid-loop, the runtime recovers the fiber and calls onFiberRecovered so the agent picks up from the last checkpoint. The SDK keeps the agent alive automatically during fiber execution — no special configuration required. For genuinely long operations, the idiomatic pattern is to start the work, persist a job ID, hibernate, and wake on a callback.

Project Think bundles three more primitives alongside fibers. Sub-agents are isolated child agents — each with its own SQLite and typed RPC — for delegating specialized work. Persistent sessions give you tree-structured conversations with forking, compaction, and FTS5 full-text search. And sandboxed code execution runs LLM-generated code in Dynamic Workers inside isolated V8 isolates with explicit capability bindings rather than ambient authority. As of this writing Project Think is in preview: the API surface is described as stable but still evolving.

import { Agent } from "agents";

export class ResearchAgent extends Agent<Env> {
  async runResearch(query: string) {
    // runFiber registers a durable invocation in SQLite before it runs.
    return this.runFiber("research", async (ctx) => {
      const plan = await this.callModel(`Plan research for: ${query}`);
      await ctx.stash({ step: "planned", plan });   // checkpoint progress

      const findings = [];
      for (const step of plan.steps) {
        const result = await this.callTool(step);   // may take many seconds
        findings.push(result);
        await ctx.stash({ step: "partial", findings }); // checkpoint each step
      }
      return this.callModel(`Synthesize: ${JSON.stringify(findings)}`);
    });
  }

  // If the instance is evicted mid-fiber, the runtime calls this on restart.
  async onFiberRecovered(name: string, stashed: unknown) {
    console.log(`Resuming fiber ${name} from`, stashed);
    // Resume from the last ctx.stash() checkpoint instead of starting over.
  }
}

Cloudflare Agents SDK vs Temporal, Restate, and DBOS: which durability model?

Cloudflare gives you edge-native durability where the checkpoint lives inside the agent’s own SQLite, while Temporal, Restate, and DBOS are server-based durable-execution engines that run an external orchestrator your agent calls into. The contrast that no incumbent guide makes is about where durability physically lives — and that single difference drives the whole decision.

With Temporal, Restate, or DBOS — the engines we cover in our durable-execution AI agents compared breakdown — your agent code emits steps to an orchestrator that owns the event history, replays your function to rebuild state, and survives crashes because the log lives in a separate, operated service. It is battle-tested, language-flexible (Python, Go, TypeScript, Java), and runs anywhere, including on AWS or GCP. The cost is operational: you run or rent the orchestration backend, and your agent’s state lives apart from its compute. With the cloudflare agents sdk, the durability is the Durable Object: the fiber checkpoint sits in the same SQLite the agent already owns, there is no separate event log to operate, and there is no network hop between the agent and its own state. The tradeoff is the inverse — you inherit Cloudflare’s per-instance ceilings (around 1,000 RPS, 10 GB SQLite) and its TypeScript-and-Workers shape, with no portable equivalent on other clouds.

So choose by where your gravity is. If your agents are per-entity, TypeScript-friendly, and you want isolation, scheduling, and durable execution without operating an orchestrator, Cloudflare’s co-located model is the lighter path. If you need one workflow engine spanning many languages and clouds, long histories far beyond a single SQLite, or you are already standardized on Temporal, a server-based engine is the safer center of gravity. The two are not strictly competitors at every layer — some teams run Temporal-style orchestration and use Cloudflare agents as the durable per-user endpoints it coordinates.

When should you build your AI agent on Cloudflare?

Build on Cloudflare when your agents are per-entity, need isolation, and benefit from co-located state and cheap hibernation; avoid it for a single high-throughput shared agent, unbounded data growth, globally latency-sensitive audiences, or Python-native stacks needing cloud portability. The one-agent-one-Durable-Object model is a precise fit for some shapes and a poor fit for others, and being honest about that is more useful than a feature list.

The cloudflare agents sdk shines for per-conversation, per-user, or per-task agents where isolation is a feature, not overhead — multi-tenant products where every tenant’s blast radius is a separate instance, real-time collaborative agents that lean on the built-in WebSocket and hibernation, and any workload that wants durable execution without standing up Temporal. It is the wrong tool when you need one shared brain handling thousands of requests per second from a single object, when an agent’s SQLite would grow past 10 GB, when your audience is global and latency-sensitive (instances pin to their creation region), or when vendor portability across AWS and GCP is a hard requirement.

If you are choosing infrastructure right now, line this up against the alternatives in our broader AI agent infrastructure guide, our best AI agent sandbox 2026 comparison, and our roundup of the top 10 AI agent SDKs of 2026. The Cloudflare Agents SDK is not the universal answer — but for stateful, per-entity agents that want durability built into the unit of compute, it is one of the most coherent runtime designs shipping in 2026.

Builder’s take

I build agent infrastructure for a living at Cyntr and Loomfeed, and the Cloudflare Agents SDK is the one runtime that genuinely changed how I reason about agent state. Most stacks bolt durability on from the outside; Cloudflare bakes it into the unit of compute. A few things I tell other builders:

• The mental model that unlocks everything is ‘one agent = one Durable Object.’ Once you accept that the agent IS the database and the scheduler, the whole API stops feeling magic and starts feeling obvious.
• Pick Cloudflare when your agents are per-entity (one per user, conversation, or task) and you want isolation for free. Do not pick it for a single high-throughput shared brain serving thousands of RPS from one instance.
• Project Think’s fibers are the first time edge-native durable execution competes head-on with Temporal and Restate. The difference is co-location: the checkpoint lives in the same SQLite the agent already owns, so there is no external orchestrator to operate.
• The thing nobody warns you about: getById with a fresh random ID spins up an empty agent every request. Always address agents by a stable name, or you will spend a day debugging ‘lost memory’ that was never persisted to the instance you thought.

Frequently asked questions

Primary sources

• Agent class internals — Cloudflare Docs
• Agents API reference — Cloudflare Docs
• Project Think: building the next generation of AI agents on Cloudflare — Cloudflare
• Cloudflare Introduces Project Think: a Durable Runtime for AI Agents — InfoQ
• Why a Cloudflare AI Agent Is Literally a Durable Object — Truvisory
• Durable Objects pricing and limits — Cloudflare Docs
• SQLite-backed Durable Objects general limits — Cloudflare Docs
• cloudflare/agents-starter — GitHub

Last updated: June 3, 2026. Related: Agent Infrastructure.