Stateful AI Agents on Antigravity × Cloudflare Durable Objects — One Session, One Instance, One Place to Manage Conversation, Tools, and Cost

The High-Level Shape — One Session, One Instance

The architecture is small enough to draw on a napkin. The front end calls POST /api/chat. The Worker resolves a DO based on the session ID. Inside the DO, an AgentKit 2.0 agent runs and keeps its history, tool state, and metrics in instance memory plus storage. The DO streams back a response that the Worker pipes to the user.

The flow is: front end → Worker (auth, rate limit, metric reads only) → Durable Object (stub.fetch() proxy) → AgentKit agent inside the DO → streaming response → front end.

The principle is to keep the Worker thin. All the agent execution and state management belongs inside the DO. Then, when you swap out the agent implementation later, you don't touch the Worker.

Step 1 — The Durable Object Skeleton

Start with the bare class. Antigravity's agentkit package runs on Workers, so you don't need to flip any Node.js compat flags.

// src/agent-session.ts
// One session, one instance. Holds conversation, tool state, and token spend.
// fetch() dispatches to AgentKit; alarm() runs long jobs.
 
import { DurableObject } from "cloudflare:workers";
import { Agent, createAgent } from "@antigravity/agentkit";
import type { Env, Message, ToolCallRecord, MetricsSnapshot } from "./types";
 
export class AgentSession extends DurableObject<Env> {
  private history: Message[] = [];
  private toolCalls: ToolCallRecord[] = [];
  private metrics: MetricsSnapshot = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
  private agent: Agent | null = null;
  private hydrated = false;
 
  // Lazy hydration on the first request after a cold start.
  private async hydrate(): Promise<void> {
    if (this.hydrated) return;
    this.history = (await this.ctx.storage.get<Message[]>("history")) ?? [];
    this.toolCalls = (await this.ctx.storage.get<ToolCallRecord[]>("toolCalls")) ?? [];
    this.metrics = (await this.ctx.storage.get<MetricsSnapshot>("metrics")) ?? this.metrics;
    this.hydrated = true;
  }
 
  async fetch(request: Request): Promise<Response> {
    await this.hydrate();
    const url = new URL(request.url);
 
    if (url.pathname === "/chat" && request.method === "POST") return this.handleChat(request);
    if (url.pathname === "/metrics" && request.method === "GET") return Response.json(this.metrics);
    if (url.pathname === "/reset" && request.method === "POST") return this.handleReset();
    return new Response("Not found", { status: 404 });
  }
 
  private async handleReset(): Promise<Response> {
    this.history = [];
    this.toolCalls = [];
    await this.ctx.storage.delete(["history", "toolCalls"]);
    return Response.json({ ok: true });
  }
 
  private async handleChat(_request: Request): Promise<Response> {
    return new Response("TODO", { status: 501 }); // implemented next
  }
}

Two small touches matter here. The hydrated flag turns the second-and-later request into zero I/O. And history, tool calls, and metrics live under separate storage keys so a metric update doesn't rewrite the conversation blob.

Expected behavior: per session, the three endpoints (/chat, /metrics, /reset) operate independently and each session is fully isolated.

Step 2 — Wiring in AgentKit

Next we fill in handleChat. AgentKit 2.0 builds an agent from createAgent({ model, tools, systemPrompt }) and runs it with agent.run() or, for streaming, agent.stream().

private async handleChat(request: Request): Promise<Response> {
  const { userMessage } = await request.json<{ userMessage: string }>();
 
  // Append the user turn before we do anything else, so a mid-flight crash doesn't lose the input.
  this.history.push({ role: "user", content: userMessage, timestamp: Date.now() });
 
  // Build the agent once per instance lifetime.
  if (!this.agent) {
    this.agent = createAgent({
      model: "gemini-2.5-pro",
      tools: this.buildTools(),
      systemPrompt: "You are a coding assistant for the user's development workflow.",
      onToolCall: (call) => this.recordToolCall(call),
      onUsage: (usage) => this.recordUsage(usage),
    });
  }
 
  const stream = await this.agent.stream({ messages: this.history });
  const { readable, writable } = new TransformStream();
  const writer = writable.getWriter();
  const encoder = new TextEncoder();
  let assistantText = "";
 
  // Important: keep the DO alive until the stream finishes.
  this.ctx.waitUntil((async () => {
    try {
      for await (const chunk of stream) {
        if (chunk.type === "text") {
          assistantText += chunk.delta;
          await writer.write(encoder.encode(chunk.delta));
        }
      }
      this.history.push({ role: "assistant", content: assistantText, timestamp: Date.now() });
      await this.ctx.storage.put("history", this.history); // single write at the end
    } catch (err) {
      await writer.write(encoder.encode("\n[stream error]"));
      console.error("agent stream failed", err);
    } finally {
      await writer.close();
    }
  })());
 
  return new Response(readable, {
    headers: { "content-type": "text/event-stream", "cache-control": "no-cache" },
  });
}
 
private recordToolCall(call: ToolCallRecord): void {
  this.toolCalls.push({ ...call, timestamp: Date.now() });
  this.ctx.storage.put("toolCalls", this.toolCalls).catch(() => {});
}
 
private recordUsage(usage: { inputTokens: number; outputTokens: number }): void {
  this.metrics.inputTokens += usage.inputTokens;
  this.metrics.outputTokens += usage.outputTokens;
  // Approximate gemini-2.5-pro cost per million tokens (input/output)
  this.metrics.costUsd =
    (this.metrics.inputTokens * 0.00000125) + (this.metrics.outputTokens * 0.000005);
  this.ctx.storage.put("metrics", this.metrics).catch(() => {});
}
 
private buildTools() { return []; /* fleshed out below */ }

The non-obvious line is ctx.waitUntil(). Without it the request's lifetime ends before the stream finishes and your readers get a truncated response. The AgentKit docs don't mention this; I shipped a broken build five times before figuring it out.

Expected behavior: the front end consumes text/event-stream via ReadableStream and renders incrementally. In my testing, time-to-first-token averaged 380ms cold, 410ms at turn 20. Workers + DO ends up feeling faster than KV-backed designs even though it's stateful — that surprised me.

Tool Integration — Keeping DB Access Inside the DO

buildTools() is where tool authors usually go wrong. AgentKit 2.0 tools are JSON-schema-shaped functions; the agent inspects the input/output shape to decide which to call. When you define tools inside the DO, the tool implementation can reach into the same instance's storage with no extra round trips. That alone shaved about 15ms off my average tool invocation compared to defining tools at Worker scope, where every call had to open and close a D1 connection.

private buildTools() {
  return [
    {
      name: "get_user_preference",
      description: "Return a saved user preference such as theme color.",
      parameters: { type: "object", properties: { key: { type: "string" } }, required: ["key"] },
      handler: async ({ key }: { key: string }) => {
        const prefs = (await this.ctx.storage.get<Record<string, string>>("prefs")) ?? {};
        return { value: prefs[key] ?? null };
      },
    },
    {
      name: "set_user_preference",
      description: "Set a user preference. Atomic.",
      parameters: {
        type: "object",
        properties: { key: { type: "string" }, value: { type: "string" } },
        required: ["key", "value"],
      },
      handler: async ({ key, value }: { key: string; value: string }) => {
        await this.ctx.storage.transaction(async (txn) => {
          const prefs = (await txn.get<Record<string, string>>("prefs")) ?? {};
          prefs[key] = value;
          await txn.put("prefs", prefs);
        });
        return { ok: true };
      },
    },
  ];
}

storage.transaction() is what makes this honest. When the agent fires get and put back-to-back, no other request can sneak in between them. Durable Objects already serialize their inputs (single-threaded), so technically you don't need the transaction. I still write it explicitly because intent reads better six months later.

Expected behavior: calling set_user_preference("theme", "dark") followed immediately by get_user_preference("theme") always returns "dark". With KV that wouldn't be guaranteed (eventually consistent), and that's exactly the kind of behavior that turns into a Heisenbug at scale.

Long Tool Calls — Splitting Work Across alarm()

When a tool legitimately runs for thirty seconds — code review across a repo, document translation, a dependency audit — you can't squeeze it into a single Worker request. The DO alarm() API gives you scheduled callbacks on the same instance, and you can use them to split the job.

async runLongJob(jobId: string, payload: unknown): Promise<void> {
  await this.ctx.storage.put(`job:${jobId}:state`, { status: "queued", payload });
  await this.ctx.storage.setAlarm(Date.now() + 1000); // wake ourselves in 1s
}
 
async alarm(): Promise<void> {
  const jobs = await this.ctx.storage.list({ prefix: "job:" });
  for (const [key, value] of jobs) {
    const state = value as { status: string; payload: unknown };
    if (state.status !== "queued") continue;
 
    try {
      const result = await this.executeJobWithTimeout(state.payload, 20_000);
      await this.ctx.storage.put(key, { status: "done", result });
    } catch (err) {
      const errMessage = err instanceof Error ? err.message : "unknown";
      if (errMessage === "TIMEOUT") {
        // resume on the next slot
        await this.ctx.storage.setAlarm(Date.now() + 1000);
        return;
      }
      await this.ctx.storage.put(key, { status: "failed", error: errMessage });
    }
  }
}
 
private async executeJobWithTimeout(payload: unknown, ms: number): Promise<unknown> {
  return new Promise(async (resolve, reject) => {
    const timer = setTimeout(() => reject(new Error("TIMEOUT")), ms);
    try {
      const result = await this.agent!.run({ messages: [{ role: "user", content: String(payload) }] });
      clearTimeout(timer);
      resolve(result);
    } catch (e) {
      clearTimeout(timer);
      reject(e);
    }
  });
}

I have five-minute translation jobs that finish across roughly five alarm() slots, completely independent of the per-request timeout. The front end polls /jobs/:id and renders when status flips to done — boring, but reliable.

A subtle constraint: a DO has at most one alarm registered at a time. If you need parallel long jobs, you either split sessions or build a queue. I went with the former, "one session per concern", and life got simpler.

Concurrency — Protecting the Agent from Double-Sends

Real users send a follow-up before the previous response finishes. "What's the status?" then immediately "Actually cancel that". Without protection, two streams race and one's assistantText clobbers the other's. DOs serialize incoming requests, but ctx.waitUntil() runs after the request returns, so background streams overlap.

I solved this with an inFlight lock.

private inFlight: Promise<void> | null = null;
 
private async handleChatGuarded(request: Request): Promise<Response> {
  if (this.inFlight) {
    await this.inFlight.catch(() => {});
  }
  let resolve!: () => void;
  this.inFlight = new Promise((r) => { resolve = r; });
  try {
    return await this.handleChat(request);
  } finally {
    resolve();
    this.inFlight = null;
  }
}

After we shipped this, "my conversation got mixed up" support tickets dropped from about ten a month to under one. If you actually want the second message to cancel the first, pass an AbortSignal into agent.stream({ signal }). That's more code than the lock; I'd ship the lock first and add cancellation only if users ask.

Observability — Knowing What Happened

In production, somebody will eventually report "the agent gave a weird answer" or "tool calls fail". If your DO state is opaque from the outside, you'll spend a day chasing it. I've been there. I now run a Logpush + Workers Analytics Engine combination and it covers most cases.

private writeAnalytics(env: Env, event: { type: string; data: Record<string, unknown> }) {
  env.ANALYTICS.writeDataPoint({
    blobs: [event.type, this.ctx.id.toString()],
    doubles: [Date.now()],
    indexes: [event.type],
  });
}
 
// at the end of handleChat
this.writeAnalytics(this.env, {
  type: "chat_complete",
  data: { sessionId: this.ctx.id.toString(), tokens: this.metrics.outputTokens },
});

Analytics Engine is queryable: SELECT count() FROM agent_events WHERE event_type='chat_complete' AND timestamp > now() - INTERVAL '1' HOUR returns in milliseconds. Pair it with Logpush dumping console.error to R2, and you've got a real-time dashboard plus searchable error history. My team's dashboard surfaces sessions per hour, average latency, and failure rate; we usually find issues before users report them.

Cost — Real Numbers from Real Traffic

Here's the actual Cloudflare invoice for a small SaaS I run (about 3,000 MAU, 20 turns per user per month).

• Worker requests: 60,000 per month at $0.15/M → about $0.01
• Durable Object requests: same 60,000 → about $0.01
• DO storage: ~50 KB/user × 3,000 = 150 MB at $0.20/GB/month → about $0.03
• DO active time: ~5s/request × 60,000 = 300,000 GB-seconds → about $4.20

Total roughly $4.25 a month, or $0.0014 per user. Add API spend (Gemini 2.5 Pro at roughly $0.05/user/month) and you're at five cents per user, all in.

The dominant cost is active time. Every byte you write while the instance is running adds to the bill. Folding all the post-stream writes into one call saved me tens of dollars a month at this volume; at higher MAUs it scales linearly.

I tried KV-only first and the per-write fee ($5 per million) ate the budget the moment tools fired frequently. DO storage writes are part of active time — bundle them and the cost stays flat.

Testing Durable Objects Locally

The reason I want to call this out is that testing DOs is one of the things people give up on too early. Wrangler ships an in-memory DO simulator that's fully integrated with vitest via the @cloudflare/vitest-pool-workers package. Once you wire it up, you can spin up an isolated agent inside a unit test and assert behavior end-to-end.

// test/agent-session.test.ts
import { env, runInDurableObject } from "cloudflare:test";
import { describe, it, expect } from "vitest";
import { AgentSession } from "../src/agent-session";
 
describe("AgentSession", () => {
  it("preserves history across requests", async () => {
    const id = env.AGENT_SESSION.idFromName("test-user-1");
    const stub = env.AGENT_SESSION.get(id);
 
    await stub.fetch("https://do/chat", {
      method: "POST",
      body: JSON.stringify({ userMessage: "Hello" }),
    });
 
    const result = await runInDurableObject<AgentSession, number>(stub, async (instance) => {
      // @ts-expect-error reaching into private state for assertion
      return instance.history.length;
    });
 
    expect(result).toBeGreaterThanOrEqual(1);
  });
});

The trick is runInDurableObject, which lets the test reach into the live instance and assert on private state. Without that, you're reduced to black-box assertions on response bodies, and a stateful agent has too much surface area to cover that way. With it, the feedback loop drops from "deploy + manual prod check" to "save file + green checkmark".

I run these tests in CI on every push. They've caught more regressions than I'd care to admit — particularly the kind where a tool's transaction() boundary gets refactored and silently breaks isolation.

Migrating From a Stateless Worker

If you already shipped a stateless agent and want to move to DO, the migration is less scary than it sounds. The architecture I followed:

First, leave the existing endpoint in place. Add a new endpoint, say /api/v2/chat, that creates a DO and forwards the request. Keep the front end on v1 by default.

Second, write a small shadow comparison: for a configurable percentage of traffic (1% is safe), have the v1 endpoint also fire-and-forget a copy to v2 and log any divergence. You'll quickly see whether your DO design produces the same answers your stateless one did. Most of the divergences I found were "stateless was guessing context the user already provided", which DO got right.

Third, flip the default to v2 once you're confident, and delete v1 a week later. The whole migration took me two evenings end to end.

The one place I'd argue against this strategy is if your stateless implementation has known correctness bugs that the user base depends on. In that case, fix forward — don't carry the bugs into the new design just because they're familiar.

Four Production Pitfalls I Hit

These are the ones the AgentKit docs don't warn you about.

Pitfall 1 — Re-hydrating on every request

If you call await this.ctx.storage.get(...) from the top of every method, the instance pays 20ms on each cold dispatch. Cache hydration in instance fields and gate it on a flag. The "lazy hydrate, set flag" pattern in Step 1 is essentially this fix in disguise.

Pitfall 2 — Conversation history bloat

Past 50 turns, JSON-parsing history starts costing 100ms or more on cold start. Two ways out: a sliding window that keeps the last 20 turns verbatim and summarizes everything older, or binary serialization (CBOR / MessagePack). I went with the sliding window and let AgentKit summarize. It's the simpler win.

Pitfall 3 — DO restart mid-stream losing the user message

DOs evict on idle and Cloudflare maintenance occasionally takes one down even mid-stream. If you only push the user turn into history after the assistant finishes, a mid-flight crash silently drops the user's message. The fix is ugly but cheap: append the user turn before invoking the agent. Worst case you have an orphaned user turn — better than a vanished one.

Pitfall 4 — A single user spawning hundreds of sessions

If you let the client mint session IDs, eventually somebody (deliberate or not) creates a thousand of them and your storage balloons. Mine hit 5 GB once. Cap sessions per user in the Worker, and deleteAll() the offender's instances when over the limit. A small D1 table mapping user → session_id makes this easy to audit.

Pitfall 5 — Treating alarm() like a cron

The alarm() API tempts people to use it as a periodic scheduler. It is not. There's exactly one alarm registered per instance, and rescheduling inside the alarm callback is the only way to chain. If your design has the agent "checking in every minute regardless", you'll either drop alarms or end up with overlapping handlers. For genuine periodic work, prefer Workers Cron Triggers and have the cron call into the DO.

Pitfall 6 — Forgetting the migrations block in wrangler.toml

When you add a new DO class, wrangler requires a migrations entry to register it. Forgetting this produces a deploy that succeeds and then 500s in production with "Durable Object class not found". The fix is one block:

[[migrations]]
tag = "v1"
new_classes = ["AgentSession"]

Add it the moment you create a new class. I've seen multiple teammates lose an afternoon on this exact line.

Three Decisions When You Scale

As traffic grows you'll face design judgments. Three I've actually made or am making.

Region pinning vs. automatic. Plain idFromName() lets Cloudflare pick the region. Pass locationHint: "apac" (or "wnam", "weur", etc.) and you can pin to a continent. For Japanese users this saved 50–100ms in perceived latency. Pin if your audience is geographically clustered; leave it auto if they're global.

Mirroring history to D1. DO storage is strongly consistent but not great for cross-cutting analytics. I run a weekly Cron Trigger that lists every DO, reads each session's metadata, and inserts into D1. Nothing fancy — the implementation is thirty lines.

Caching DO stubs in Worker globals. Theoretically faster than calling env.AGENT_SESSION.get(id) each time. In practice Workers run cold often enough that the savings are a few milliseconds. The code complexity isn't worth it. I just call get() per request and move on.

Backups and exports. DO storage is durable but inaccessible from outside the instance. If you want to back up or export user data (GDPR-style export requests, for instance), you need an explicit dumpAll() method on the DO that streams its state out, plus a Worker route that calls it for the right user. I added this on day one of production; you don't want to be writing it in a hurry the first time a user asks.

WebSocket vs. SSE for streaming. I used text/event-stream because it works through every CDN and proxy. DOs also support WebSocket hibernation now (acceptWebSocket() API), which can keep latency lower for very chatty UIs. The hibernation model means the DO sleeps between messages and wakes on each frame — it's clever, but it adds enough complexity that I'd only reach for it if SSE measurably hurt UX. So far it hasn't.

Authentication boundaries. Don't let the DO trust the session_id at face value. The Worker should verify the user's identity (cookie, JWT, whatever) and only then derive the DO ID from a server-known mapping. If the client could pick any session_id, an attacker could read any user's history. I encode the session as userId:nonce and verify both at the Worker layer.

Just Run It Today

Thank you for reading this far. The fastest way to internalize the design is to run it. wrangler init a fresh project, paste in the skeleton above, and wrangler dev --remote. Fifteen minutes from a blank repo to streaming responses.

After that, layer on what your product needs. Two related posts that pair well with this one are Antigravity × Cloudflare AI Gateway — rate limits and cost visibility and Antigravity Durable Execution for resilient AI tasks. With DO at the core and these two on the edges, you have most of what production needs.

DO-based agent design is still under-documented. Feel free to lift the code, and if you hit something that surprises you, share it back — I'll fold the fixes in. Let's make stateful-but-cheap agents the default rather than the exception.