# One Durable Object per agent

Why I gave every AI agent its own Durable Object with a SQLite task ledger, and what that bought in state, concurrency and debuggability.

By Elson Tan (https://elsontan.com)
Published: 2026-06-02
Updated: 2026-08-01
Reading time: 4 min
Tags: Cloudflare, Architecture, Agents
Canonical: https://elsontan.com/blog/one-durable-object-per-agent/

> Giving each AI agent its own Durable Object with an embedded SQLite ledger makes request ordering a platform guarantee rather than application code. It removes optimistic locking, read-your-writes races and distributed locks, at the cost of harder cross-agent analytics and a per-object storage lifecycle.

---
When you build a multi-tenant agent platform, the first architectural question is where
conversation state lives. The default answer is a shared database keyed by conversation ID,
with a stateless worker reading and writing rows. It works, and it is what most teams reach
for. I went the other way: **one [Durable Object](https://developers.cloudflare.com/durable-objects/)
per agent**, holding conversation state, memory and a task ledger in its own embedded SQLite.

## What does a single-tenant object actually buy you?

A Durable Object is a single-threaded, addressable actor with strongly consistent storage
attached. Requests for the same agent ID land on the same object, in order. That property
alone removes an entire class of problem:

- No optimistic locking around conversation appends.
- No read-your-writes race between a tool result and the next turn.
- No distributed lock to stop two concurrent messages double-spending a rate budget.

The concurrency model is the feature. You get serialisation because the platform gives it to
you, not because you built a queue. Cloudflare documents the guarantee directly: each object
has [a single-threaded execution model](https://developers.cloudflare.com/durable-objects/platform/known-issues/),
and storage operations are backed by
[a SQLite database per object](https://developers.cloudflare.com/durable-objects/best-practices/access-durable-objects-storage/).

## The task ledger

Conversation history alone is not enough state for an agent that does real work. Long-running
tool calls need to survive an eviction, and a user needs to be able to ask what happened. So
every unit of work goes into a ledger table inside the object.

The class extends `DurableObject` from `cloudflare:workers` and takes the SQLite handle off
the context in the constructor. That handle is
[`ctx.storage.sql`](https://developers.cloudflare.com/durable-objects/api/sql-storage/), and
`exec()` takes a query plus positional bindings:

```ts
import { DurableObject } from 'cloudflare:workers'

export class Agent extends DurableObject {
  sql: SqlStorage

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env)
    this.sql = ctx.storage.sql

    this.sql.exec(`
      CREATE TABLE IF NOT EXISTS tasks(
        id          TEXT PRIMARY KEY,
        parent_id   TEXT,
        kind        TEXT NOT NULL,
        status      TEXT NOT NULL,
        input       TEXT NOT NULL,
        output      TEXT,
        tokens_in   INTEGER DEFAULT 0,
        tokens_out  INTEGER DEFAULT 0,
        created_at  INTEGER NOT NULL,
        finished_at INTEGER
      );
    `)
  }

  recordTask(id: string, parentId: string | null, kind: string, input: unknown) {
    this.sql.exec(
      `INSERT INTO tasks (id, parent_id, kind, status, input, created_at)
       VALUES (?, ?, ?, 'running', ?, ?)`,
      id,
      parentId,
      kind,
      JSON.stringify(input),
      Date.now()
    )
  }

  // A delegation tree falls out of one recursive query.
  tree(rootId: string) {
    return this.sql
      .exec(
        `WITH RECURSIVE walk(id) AS (
           SELECT id FROM tasks WHERE id = ?
           UNION ALL
           SELECT t.id FROM tasks t JOIN walk w ON t.parent_id = w.id
         )
         SELECT t.* FROM tasks t JOIN walk USING (id) ORDER BY t.created_at`,
        rootId
      )
      .toArray()
  }
}
```

The class needs a SQLite-backed migration in the Wrangler config, not the older key-value
class binding:

```toml
[[durable_objects.bindings]]
name = "AGENT"
class_name = "Agent"

[[migrations]]
tag = "v1"
new_sqlite_classes = ["Agent"]
```

Because `parent_id` is there, a delegation tree is one recursive query. When someone asks why
an agent answered the way it did, you can show them the actual tree of sub-agent calls with
token counts on each node, rather than reconstructing it from log lines.

## Delegation: synchronous or ephemeral

The orchestrator inside an agent object has two ways to hand off work.

For anything short, it calls the sub-agent synchronously and blocks the turn. Simple, and the
result lands in the same ledger write.

For anything long, it spawns an ephemeral queue object: a separate Durable Object created for
that one job, which does the work, writes back to the parent's ledger, and then deletes
itself. The parent stays responsive. The user gets a task ID immediately and a proactive
message when it finishes. Work that must survive the request uses
[`ctx.waitUntil`](https://developers.cloudflare.com/workers/runtime-apis/context/) or an
[alarm](https://developers.cloudflare.com/durable-objects/api/alarms/) rather than a dangling
promise.

The rule I settled on is a time budget, not a task type. If the estimated work exceeds a few
seconds, it goes ephemeral.

## The costs, honestly

This is not free.

**Storage is per object.** A million agents means a million small SQLite databases. Cheap per
unit, but you need a lifecycle policy, and you need it before you have a million of them.
Cloudflare publishes the per-object limits, including database size, in
[the Durable Objects limits page](https://developers.cloudflare.com/durable-objects/platform/limits/);
read them before you design around the model.

**Cross-agent queries are hard.** Asking "how many tokens did this tenant spend today" cannot
be a single query against a shared table any more. I stream metering events out to an
analytics store and treat the objects as the source of truth for behaviour, not for
reporting.

**Cold starts exist.** An object that has not been touched in a while pays a wake-up cost.
For a chat interface it is unnoticeable. For a latency-critical synchronous API it might not
be.

For an agent platform, where the workload is naturally partitioned by agent and the hard
problems are ordering and state rather than analytics, the trade has been clearly worth it.

## Sources

- [Durable Objects overview](https://developers.cloudflare.com/durable-objects/), Cloudflare
- [Durable Objects SQL storage API](https://developers.cloudflare.com/durable-objects/api/sql-storage/), Cloudflare
- [Access Durable Objects storage](https://developers.cloudflare.com/durable-objects/best-practices/access-durable-objects-storage/), Cloudflare
- [Durable Objects alarms](https://developers.cloudflare.com/durable-objects/api/alarms/), Cloudflare
- [Durable Objects limits](https://developers.cloudflare.com/durable-objects/platform/limits/), Cloudflare