Persistent State

this.setState() merges a patch into the actor’s current state. Use it for small structured values you want to read quickly — the current conversation state, user preferences, last-seen timestamp.

export interface MyState extends Record<string, unknown> {
  status: "idle" | "processing" | "waiting";
  lastReply: string;
  at: number;
}

export class MyAgent extends Agent<RuntimeEnv, MyState> {
  // Default state for a new actor
  protected override initialState(): MyState {
    return { status: "idle", lastReply: "", at: 0 };
  }

  async process(): Promise<void> {
    await this.setState({ status: "processing" });
    // ... do work ...
    await this.setState({ status: "idle", lastReply: "Done.", at: Date.now() });
  }

  async report(): Promise<MyState> {
    return this.getState();
  }
}

setState is a recursive merge (RFC 7396) — top-level keys you pass are merged in, nested objects are deep-merged, and null deletes a key. replaceState replaces the whole state object. State is one value, read whole. The moment data turns relational or queryable — orders, events, anything you’d filter or aggregate — put it in the actor’s embedded SQL database instead.

Where this is stored

(SDK ≥ 0.13.0) An agent’s four persistent stores — the state above, message history, progress events, and scheduled tasks — are kept in a per-actor SQL database rather than in key/value entries. This is the SDK’s own storage layer, separate from the SQL database you open yourself at this.ctx.storage.sql. Nothing in the API changed: the same calls, with the same semantics, read and write the same data. What changes is how they scale — reads no longer degrade as a log grows, so messages.all() and events.read() on a long-lived agent stay flat instead of getting slower every turn. An agent that already has data migrates itself, once, the first time it writes after picking up 0.13.0 — not on first activation, so an agent that is only read from stays where it is until something writes to it. There is nothing to run and no downtime.

Do not roll back across 0.13.0. Once an agent has migrated, an SDK that predates the migration does not know to look in the SQL database and reads the actor as empty — its state, history, events, and schedules are all still stored, but no longer visible to your code. Upgrading is safe; downgrading is not.

Get Started

Concepts

Build

Examples

Reference

For AI Agents

Persistent State

Where this is stored

​Where this is stored

Where this is stored