导航|地址|刷新
Store and sync state

Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.



DocsDirectoryAPISDKsChangelog

Search

Log in






Agents

/




Overview


Getting started


Quick start

Add to existing project

Testing your Agents






Concepts


What are agents?

Conversation state and memory

Tools

Calling LLMs

Using Agents with Workflows


Agentic patterns


Overview

Human-in-the-loop patterns

Long-running agents










Communication channels



Chat


Chat agents

Autonomous responses

Client SDK





Voice

Email

Slack


Webhooks


Overview

Push notifications










Tools


Sandbox

MCP

Browser

AI Search


Agentic Payments


Overview

Charge for HTTP content


x402


Overview

Charge for HTTP content

Charge for MCP tools

Pay from Agents SDK

Pay from coding tools





MPP (Machine Payments Protocol)






Code Mode


Overview

Create a durable Code Mode runtime

AI SDK integration

Use Code Mode with TanStack AI

Browser-owned tools

MCP

OpenAPI

How Code Mode works

Code Mode API reference










Harnesses


Overview


Think


Overview

Getting started

Configuration

Tools

Actions

Lifecycle hooks

Client tools

Messengers

Channels

Scheduled tasks

Workflows

Sub-agent RPC and programmatic turns

Programmatic submissions

Durable recovery










Runtime


Agents API


Lifecycle


Agent class internals

Callable methods

Store and sync state

Sessions

getCurrentAgent()






Communication


Routing

WebSockets

HTTP and Server-Sent Events

Chat SDK

Protocol messages

Readonly connections






Execution


Sub-agents

Schedule tasks

Durable execution with fibers

Queue tasks

Retries

Run Workflows

Agents as tools

Agent Skills






Operations


Configuration

Cross-domain authentication

Using AI Models

Observability










Examples


Chat agent

Slack agent

Voice agent

Browser agent

Email agent






Model Context Protocol (MCP)


Overview


APIs


MCP handler APIs

McpAgent

McpClient






Protocol


Tools

Authorization

Transport

MCP governance






Guides


Build MCP client

Build a Remote MCP server

Test a Remote MCP Server

Securing MCP servers

Connect to an MCP server

Handle OAuth with MCP servers

Migrate to MCP SDK v2

Build a single-tool Code Mode MCP server

Build a search and execute MCP server






Cloudflare


MCP server portals ↗


Cloudflare's own MCP servers


Overview

Cloudflare Community MCP Server









Code Mode MCP server patterns






Platform


Limits






Agent resources


Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Agents llms.txt ↗

Agents llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗













Home

/Agents

/…
Runtime


/Lifecycle

/Store and sync state



Store and sync state


Last updated Jun 3, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewOverviewDefining initial state Type safety When initial state appliesReading state Undefined stateUpdating state State must be serializableResponding to state changes The source parameter Common pattern: Client-driven actionsValidating state updatesClient-side state sync React (useAgent) Vanilla JS (AgentClient) State flowState from WorkflowsSQL APIBest practices Keep state small Optimistic updates State vs SQL Avoid infinite loopsUse Agent state as model contextAPI reference Properties Methods Workflow step methodsNext steps




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


Overview


State within an Agent is:

Persistent - Automatically saves to SQLite, survives restarts and hibernation

Synchronized - Changes are broadcast to all connected WebSocket clients instantly

Bidirectional - Both server and clients can update state

Type-safe - Full TypeScript support with generics

Immediately consistent - Read your own writes

Thread-safe - Safe for concurrent updates

Fast - State is colocated wherever the Agent is running

Agent state is stored in a SQL database embedded within each individual Agent instance. You can interact with it using the higher-level this.setState API (recommended), which allows you to sync state and trigger events on state changes, or by directly querying the database with this.sql.


State vs Props


State is persistent data that survives restarts and syncs across clients. Props are one-time initialization arguments passed when an agent is instantiated - use props for configuration that does not need to persist.








import { Agent } from "agents";export class GameAgent extends Agent { // Default state for new agents initialState = { players: [], score: 0, status: "waiting", }; // React to state changes onStateChanged(state, source) { if (source !== "server" && state.players.length >= 2) { // Client added a player, start the game this.setState({ ...state, status: "playing" }); } } addPlayer(name) { this.setState({ ...this.state, players: [...this.state.players, name], }); }}

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:






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

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 defines your state type:






// State is fully typedexport class MyAgent extends Agent { initialState = { count: 0 }; increment() { // TypeScript knows this.state is MyState this.setState({ count: this.state.count + 1 }); }}

// State is fully typedexport 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:

New agent - initialState is used and persisted

Existing agent - Persisted state is loaded from SQLite

No initialState defined - this.state is undefined






class MyAgent extends Agent { initialState = { count: 0 }; async onStart() { // Safe to access - returns initialState if new, or persisted state console.log("Current count:", this.state.count); }}

class MyAgent extends Agent<Env, { count: number }> { initialState = { count: 0 }; async onStart() { // Safe to access - returns initialState if new, or persisted state console.log("Current count:", this.state.count); }}





Reading state


Access the current state via the this.state getter:






class MyAgent extends Agent { async onRequest(request) { // Read current state const { players, status } = this.state; if (status === "waiting" && players.length < 2) { return new Response("Waiting for players..."); } return Response.json(this.state); }}

class MyAgent extends Agent< Env, { players: string[]; status: "waiting" | "playing" | "finished" }> { async onRequest(request: Request) { // Read current state const { players, status } = this.state; if (status === "waiting" && players.length < 2) { return new Response("Waiting for players..."); } return Response.json(this.state); }}





Undefined state


If you do not define initialState, this.state returns undefined:






export class MinimalAgent extends Agent { // No initialState defined async onConnect(connection) { if (!this.state) { // First time - initialize state this.setState({ initialized: true }); } }}

export class MinimalAgent extends Agent { // No initialState defined async onConnect(connection: Connection) { if (!this.state) { // First time - initialize state this.setState({ initialized: true }); } }}





Updating state


Use setState() to update state. This:

Saves to SQLite (persistent)

Broadcasts to all connected clients (excluding connections where shouldSendProtocolMessages returned false)

Triggers onStateChanged() (after broadcast; best-effort)






// Replace entire statethis.setState({ players: ["Alice", "Bob"], score: 0, status: "playing",});// Update specific fields (spread existing state)this.setState({ ...this.state, score: this.state.score + 10,});

// Replace entire statethis.setState({ players: ["Alice", "Bob"], score: 0, status: "playing",});// Update specific fields (spread existing state)this.setState({ ...this.state, score: this.state.score + 10,});





State must be serializable


State is stored as JSON, so it must be serializable:






// Good - plain objects, arrays, primitivesthis.setState({ items: ["a", "b", "c"], count: 42, active: true, metadata: { key: "value" },});// Bad - functions, classes, circular references// Functions do not serialize// Dates become strings, lose methods// Circular references fail// For dates, use ISO stringsthis.setState({ createdAt: new Date().toISOString(),});

// Good - plain objects, arrays, primitivesthis.setState({ items: ["a", "b", "c"], count: 42, active: true, metadata: { key: "value" },});// Bad - functions, classes, circular references// Functions do not serialize// Dates become strings, lose methods// Circular references fail// For dates, use ISO stringsthis.setState({ createdAt: new Date().toISOString(),});





Responding to state changes


Override onStateChanged() to react when state changes (notifications/side-effects):






class MyAgent extends Agent { onStateChanged(state, source) { console.log("State updated:", state); console.log("Updated by:", source === "server" ? "server" : source.id); }}

class MyAgent extends Agent<Env, GameState> { onStateChanged(state: GameState, source: Connection | "server") { console.log("State updated:", state); console.log("Updated by:", source === "server" ? "server" : source.id); }}





The source parameter


The source shows who triggered the update:

Value	Meaning
"server"	Agent called setState()
Connection	A client pushed state via WebSocket

This is useful for:

Avoiding infinite loops (do not react to your own updates)

Validating client input

Triggering side effects only on client actions






class MyAgent extends Agent { onStateChanged(state, source) { // Ignore server-initiated updates if (source === "server") return; // A client updated state - validate and process const connection = source; console.log(`Client ${connection.id} updated state`); // Maybe trigger something based on the change if (state.status === "submitted") { this.processSubmission(state); } }}

class MyAgent extends Agent< Env, { status: "waiting" | "playing" | "finished" }> { onStateChanged(state: GameState, source: Connection | "server") { // Ignore server-initiated updates if (source === "server") return; // A client updated state - validate and process const connection = source; console.log(`Client ${connection.id} updated state`); // Maybe trigger something based on the change if (state.status === "submitted") { this.processSubmission(state); } }}





Common pattern: Client-driven actions







class MyAgent extends Agent { onStateChanged(state, source) { if (source === "server") return; // Client added a message const lastMessage = state.messages[state.messages.length - 1]; if (lastMessage && !lastMessage.processed) { // Process and update this.setState({ ...state, messages: state.messages.map((m) => m.id === lastMessage.id ? { ...m, processed: true } : m, ), }); } }}

class MyAgent extends Agent<Env, { messages: Message[] }> { onStateChanged(state: State, source: Connection | "server") { if (source === "server") return; // Client added a message const lastMessage = state.messages[state.messages.length - 1]; if (lastMessage && !lastMessage.processed) { // Process and update this.setState({ ...state, messages: state.messages.map((m) => m.id === lastMessage.id ? { ...m, processed: true } : m, ), }); } }}





Validating state updates


If you want to validate or reject state updates, override validateStateChange():

Runs before persistence and broadcast

Must be synchronous

Throwing aborts the update






class MyAgent extends Agent { validateStateChange(nextState, source) { // Example: reject negative scores if (nextState.score < 0) { throw new Error("score cannot be negative"); } // Example: only allow certain status transitions if (this.state.status === "finished" && nextState.status !== "finished") { throw new Error("Cannot restart a finished game"); } }}

class MyAgent extends Agent<Env, GameState> { validateStateChange(nextState: GameState, source: Connection | "server") { // Example: reject negative scores if (nextState.score < 0) { throw new Error("score cannot be negative"); } // Example: only allow certain status transitions if (this.state.status === "finished" && nextState.status !== "finished") { throw new Error("Cannot restart a finished game"); } }}





Note


onStateChanged() is not intended for validation; it is a notification hook and should not block broadcasts. Use validateStateChange() for validation.




Client-side state sync


State synchronizes automatically with connected clients.


React (useAgent)







import { useAgent } from "agents/react";function GameUI() { const agent = useAgent({ agent: "game-agent", name: "room-123", onStateUpdate: (state, source) => { console.log("State updated:"
…(内容过长已截断)

------
导航页 打开网址