State

Agent state is one persistent value of your State type. setState merges, which is what you want for the common case — update two fields without re-writing the rest.

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

export class Conversation extends Agent<Env, ConvState> {
  protected override initialState(): ConvState {
    return { status: "idle", lastReply: "", at: 0 };
  }

  async process(): Promise<void> {
    await this.setState({ status: "processing" });          // merge: other keys untouched
    // ...
    await this.setState({ status: "idle", at: Date.now() });
  }
}

State lives in the actor’s persistent storage — the same layer the scheduler and the message log write to — as a single entry holding the whole State value. Reads return that value in full, and setState re-persists it inside a storage transaction, so keep it small and fixed-shape: status flags, cursors, the instance’s working memory. It follows the storage layer’s codec rules and per-value size cap (see the storage reference). For data that accumulates or needs querying — rows you’d filter, aggregate, or join — use the agent’s embedded SQL database instead; it lives in the same instance and scales to 1 GB per agent.

initialState()

getState()

setState()

The merge is recursive, and null deletes:

// stored: { status: "processing", job: { id: "j1", step: 2, note: "retrying" } }
await this.setState({ job: { step: 3, note: null } });
// stored: { status: "processing", job: { id: "j1", step: 3 } }

Untouched keys survive at every level — status and job.id were never rewritten.

replaceState()

onStateChanged()

One override fans state out to connected clients — broadcastSnapshot pushes to every socket subscribed to state, and the hook covers setState and replaceState alike:

private desk = new AgentSocketServer<ConvState>(this, {
  getState: () => this.getState(),
});

protected override async onStateChanged(next: ConvState, prev: ConvState): Promise<void> {
  await this.desk.broadcastSnapshot(next);
}

For patch-level pushes — sending only what changed — broadcast from a setState override instead, where the patch object is in hand; the example on AgentSocketServer shows that variant.

Get Started

Concepts

Build

Examples

Reference

For AI Agents

initialState()

getState()

setState()

replaceState()

onStateChanged()

​initialState()

​getState()

​setState()

​replaceState()

​onStateChanged()

initialState()

getState()

setState()

replaceState()

onStateChanged()