state

State Management

Agents provide built-in state management with automatic persistence and real-time synchronization across all connected clients.

Overview

Agent state is:

• Persistent - Automatically saved to SQLite, survives restarts and hibernation
• Synchronized - Changes broadcast to all connected WebSocket clients instantly
• Bidirectional - Both server and clients can update state
• Type-safe - Full TypeScript support with generics

import { Agent } from "agents";

type GameState = {
  players: string[];
  score: number;
  status: "waiting" | "playing" | "finished";
};

export class GameAgent extends Agent<Env, GameState> {
  // Default state for new agents
  initialState: GameState = {
    players: [],
    score: 0,
    status: "waiting"
  };

  // React to state changes
  onStateChanged(state: GameState, source: Connection | "server") {
    if (source !== "server" && state.players.length >= 2) {
      // Client added a player, start the game
      this.setState({ ...state, status: "playing" });
    }
  }

  addPlayer(name: string) {
    this.setState({
      ...this.state,
      players: [...this.state.players, name]
    });
  }
}

Defining Initial State

Use the initialState property to define default values for new agent instances:

type State = {
  messages: Message[];
  settings: UserSettings;
  lastActive: string | null;
};

export class ChatAgent extends Agent<Env, State> {
  initialState: State = {
    messages: [],
    settings: { theme: "dark", notifications: true },
    lastActive: null
  };
}

Type Safety

The second generic parameter to Agent<Env, State> defines your state type:

// State is fully typed
export class MyAgent extends Agent<Env, MyState> {
  initialState: MyState = { count: 0 };

  increment() {
    // TypeScript knows this.state is MyState
    this.setState({ count: this.state.count + 1 });
  }
}

When Initial State Applies

Initial state is applied lazily on first access, not on every wake: