store and sync state

Author: elithrar

public/_redirects

@@ -99,7 +99,7 @@
 # agents
 /agents/build/prompts/ /workers/get-started/prompting/ 301
 /agents/examples/browse-the-web/ /agents/api-reference/browse-the-web/ 301
-/agents/examples/manage-and-sync-state/ /agents/api-reference/manage-and-sync-state/ 301
+/agents/examples/manage-and-sync-state/ /agents/api-reference/store-and-sync-state/ 301
 /agents/examples/rag/ /agents/api-reference/rag/ 301
 /agents/examples/run-workflows/ /agents/api-reference/run-workflows/ 301
 /agents/examples/schedule-tasks/ /agents/api-reference/schedule-tasks/ 301

src/content/docs/agents/api-reference/sdk.mdx

@@ -493,7 +493,7 @@ export default MyAgent;
 
 :::note
 
-To learn more about how to manage state within an Agent, refer to the documentation on [managing and syncing state](/agents/api-reference/manage-and-sync-state/).
+To learn more about how to manage state within an Agent, refer to the documentation on [managing and syncing state](/agents/api-reference/store-and-sync-state/).
 
 :::
 

src/content/docs/agents/api-reference/manage-and-sync-state.mdx renamed to src/content/docs/agents/api-reference/store-and-sync-state.mdx

@@ -1,20 +1,23 @@
 ---
-title: Manage and sync state
+title: Store and sync state
 pcx_content_type: concept
 sidebar:
   order: 6
 ---
 
 import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
 
-Every Agent has built-in state management capabilities, including built-in storage and synchronization between the Agent and frontend applications. State within an Agent is:
+Every Agent has built-in state management capabilities, including built-in storage and synchronization between the Agent and frontend applications.
 
-* Persisted across Agent restarts: data is permanently persisted within the Agent.
+State within an Agent is:
+
+* Persisted across Agent restarts: data is permanently stored within an Agent.
 * Automatically serialized/deserialized: you can store any JSON-serializable data.
 * Immediately consistent within the Agent: read your own writes.
 * Thread-safe for concurrent updates
+* Fast: state is colocated wherever the Agent is running. Reads and writes do not need to traverse the network.
 
-Agent state is stored in a SQL database that is embedded within each individual Agent instance: you can interact with it using the higher-level `this.setState` API (recommended) or by directly querying the database with `this.sql`.
+Agent state is stored in a SQL database that is 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 API
 

src/content/docs/agents/api-reference/using-ai-models.mdx

@@ -75,7 +75,7 @@ export class MyAgent extends Agent<Env> {
 
 </TypeScriptExample>
 
-You can also persist AI model responses back to [Agent's internal state](/agents/api-reference/manage-and-sync-state/) by using the `this.setState` method. For example, if you run a [scheduled task](/agents/api-reference/schedule-tasks/), you can store the output of the task and read it later. Or, if a user disconnects, read the message history back and send it to the user when they reconnect.
+You can also persist AI model responses back to [Agent's internal state](/agents/api-reference/store-and-sync-state/) by using the `this.setState` method. For example, if you run a [scheduled task](/agents/api-reference/schedule-tasks/), you can store the output of the task and read it later. Or, if a user disconnects, read the message history back and send it to the user when they reconnect.
 
 ### Workers AI
 

src/content/docs/agents/api-reference/websockets.mdx

@@ -120,7 +120,7 @@ function AgentInterface() {
 ```
 </TypeScriptExample>
 
-The `useAgent` hook automatically handles the lifecycle of the connection, ensuring that it is properly initialized and cleaned up when the component mounts and unmounts. You can also [combine `useAgent` with `useState`](/agents/api-reference/manage-and-sync-state/) to automatically synchronize state across all clients connected to your Agent.
+The `useAgent` hook automatically handles the lifecycle of the connection, ensuring that it is properly initialized and cleaned up when the component mounts and unmounts. You can also [combine `useAgent` with `useState`](/agents/api-reference/store-and-sync-state/) to automatically synchronize state across all clients connected to your Agent.
 
 ## Handling WebSocket events
 

src/content/docs/agents/index.mdx

@@ -50,7 +50,7 @@ Dive into the [Agent SDK reference](/agents/api-reference/sdk/) to learn more ab
 
 We built the `agents-sdk` with a few things in mind:
 
-- **Batteries (state) included**: Agents come with [built-in state management](/agents/api-reference/manage-and-sync-state/), with the ability to automatically sync state between an Agent and clients, trigger events on state changes, and read+write to each Agent's SQL database.
+- **Batteries (state) included**: Agents come with [built-in state management](/agents/api-reference/store-and-sync-state/), with the ability to automatically sync state between an Agent and clients, trigger events on state changes, and read+write to each Agent's SQL database.
 - **Communicative**: You can connect to an Agent via [WebSockets](/agents/api-reference/websockets/) and stream updates back to client in real-time. Handle a long-running response from a reasoning model, the results of an [asynchronous workflow](/agents/api-reference/run-workflows/), or build a chat app that builds on the `useAgent` hook included in the `agents-sdk`.
 - **Extensible**: Agents are code. Use the [AI models](/agents/api-reference/using-ai-models/) you want, bring-your-own headless browser service, pull data from your database hosted in another cloud, add your own methods to your Agent and call them.