state state state

Author: elithrar

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

@@ -6,7 +6,7 @@ sidebar:
 
 ---
 
-import { MetaInfo, Render, Type, WranglerConfig } from "~/components";
+import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
 
 At its most basic, an Agent is a JavaScript class that extends the `Agent` class from the `@cloudflare/agents` package. An Agent encapsulates all of the logic for an Agent, including how clients can connect to it, how it stores state, the methods it exposes, and any error handling.
 
@@ -28,7 +28,135 @@ An Agent can have many (millions of) instances: each instance is a separate micr
 
 Instances of an Agent are addressed by a unique identifier: that identifier (ID) can be the user ID, an email address, GitHub username, a flight ticket number, an invoice ID, or any other identifier that helps to uniquely identify the instance and for whom it is acting on behalf of.
 
-## Agent
+## The Agent class
 
-TODO - agent class
+Writing an Agent requires you to define a class that extends the `Agent` class from the `@cloudflare/agents` package. An Agent encapsulates all of the logic for an Agent, including how clients can connect to it, how it stores state, the methods it exposes, and any error handling.
 
+An Agent has the following class methods:
+
+<TypeScriptExample>
+
+```ts
+import { Agent } from "@cloudflare/agents";
+
+interface Env {
+	// Define environment variables & bindings here
+}
+
+// Pass the Env as a TypeScript type argument
+// Any services connected to your Agent or Worker as Bindings
+// are then available on this.env.<BINDING_NAME>
+class MyAgent extends Agent<Env> {
+	// Called when an Agent is started (or woken up)
+	async onStart() {
+		// Can access this.env and this.state
+		console.log('Agent started');
+	}
+
+	// Called when a HTTP request is received
+	// Can be connected to routeAgentRequest to automatically route
+	// requests to an individual Agent.
+	async onRequest(request: Request) {
+			console.log("Received request!");
+	}
+
+	// Called when a WebSocket connection is established
+	async onConnect(connection: Connection, ctx: ConnectionContext) {
+		console.log("Connected!");
+		// Check the request at ctx.request
+		// Authenticate the client
+		// Give them the OK.
+		connection.accept();
+	}
+
+	// Called for each message received on the WebSocket connection
+	async onMessage(connection: Connection, message: WSMessage) {
+		console.log(`message from client ID: ${connection.id}`)
+		// Send messages back to the client
+		connection.send("Hello!");
+	}
+
+	// WebSocket error and disconnection (close) handling.
+	async onError(connection: Connection, error: unknown): Promise<void> {
+		console.error(`WS error: ${error}`);
+	}
+
+	async onClose(connection: Connection, code: number, reason: string, wasClean: boolean): Promise<void> {
+		console.log(`WS closed: ${code} - ${reason} - wasClean: ${wasClean}`);
+		connection.close();
+	}
+
+	// Called when the Agent's state is updated
+	// via this.setState or the useAgent hook from the @cloudflare/agents/react package.
+	async onStateUpdate(state: any) {
+		// 'state' will be typed if you supply a type parameter to the Agent class.
+	}
+}
+
+export default MyAgent;
+```
+
+</TypeScriptExample>
+
+:::note
+
+To learn more about how to manage state within an Agent, refer to the documentation on [managing and syncing state](/agents/examples/manage-and-sync-state/).
+
+:::
+
+You can also define your own methods on an Agent: it's technically valid to publish an Agent only has your own methods exposed, and create/get Agents directly from a Worker.
+
+Your own methods can access the Agent's environment variables and bindings on `this.env`, state on `this.setState`, and call other methods on the Agent via `this.yourMethodName`.
+
+## Calling Agents from Workers
+
+You can create and run an instance of an Agent directly from a Worker in one of three ways:
+
+1. Using the `routeAgentRequest` helper: this will automatically map requests to an individual Agent based on the `/agents/:agent/:name` URL pattern.
+2. Calling `getAgentByName`, which will create a new Agent instance if none exists by that name, or retrieve a handle to an existing instance.
+3. The [Durable Objects stub API](/durable-objects/api/id/), which provides a lower level API for creating and retrieving Agents.
+
+These three patterns are shown below: we recommend using either `routeAgentRequest` or `getAgentByName`, which help avoid some boilerplate.
+
+<TypeScriptExample>
+
+```ts
+import { Agent, AgentNamespace, getAgentByName, routeAgentRequest } from '@cloudflare/agents';
+
+interface Env {
+	// Define your Agent on the environment here
+	// Passing your Agent class as a TypeScript type parameter allows you to call
+	// methods defined on your Agent.
+	MyAgent: AgentNamespace<MyAgent>;
+}
+
+export default {
+	async fetch(request, env, ctx): Promise<Response> {
+		// Routed addressing
+		// Automatically routes HTTP requests and/or WebSocket connections to /agents/:agent/:name
+		// Best for: connecting React apps directly to Agents using useAgent from @cloudflare/agents/react
+		(await routeAgentRequest(request, env)) || Response.json({ msg: 'no agent here' }, { status: 404 });
+
+		// Named addressing
+		// Best for: convenience method for creating or retrieving an agent by name/ID.
+		let namedAgent = getAgentByName<Env, MyAgent>(env.MyAgent, 'my-unique-agent-id');
+		// Pass the incoming request straight to your Agent
+		let namedResp = (await namedAgent).fetch(request);
+
+		// Durable Objects-style addressing
+		// Best for: controlling ID generation, associating IDs with your existing systems,
+		// and customizing when/how an Agent is created or invoked
+		const id = env.MyAgent.newUniqueId();
+		const agent = env.MyAgent.get(id);
+		// Pass the incoming request straight to your Agent
+		let resp = await agent.fetch(request);
+
+		return Response.json({ hello: 'visit https://developers.cloudflare.com/agents for more' });
+	},
+} satisfies ExportedHandler<Env>;
+
+export class MyAgent extends Agent<Env> {
+	// Your Agent implementation goes here
+}
+```
+</TypeScriptExample>

src/content/docs/agents/examples/index.mdx

@@ -3,12 +3,10 @@ pcx_content_type: reference
 title: Build
 sidebar:
   order: 4
-  group:
-    hideIndex: true
 ---
 
-import { DirectoryListing } from "~/components";
+import { DirectoryListing, PackageManagers } from "~/components";
 
-Build AI Agents on Cloudflare
+Agents running on Cloudflare can:
 
 <DirectoryListing />

src/content/docs/agents/examples/manage-and-sync-state.mdx

@@ -14,9 +14,11 @@ Every Agent has built-in state management capabilities, including built-in stora
 * Immediately consistent within the Agent: read your own writes.
 * Thread-safe for concurrent updates
 
-### State management
+Agent state is stored in SQL database that associate with each indidivual Agent instance: you can interact with it using the higher-level `this.setState` API (recommended) or by directly querying the database with `this.sql`.
 
-Every agent has built-in state management capabilities. You can set and update the agent's state directly using `this.state`:
+### State API
+
+Every agent has built-in state management capabilities. You can set and update the agent's state directly using `this.setState`:
 
 <TypeScriptExample>
 
@@ -51,6 +53,32 @@ export class MyAgent extends Agent {
 
 </TypeScriptExample>
 
+If you're using TypeScript, you can also provide a type for your Agent's state by passing in a type as a [type parameter](https://www.typescriptlang.org/docs/handbook/2/generics.html#using-type-parameters-in-generic-constraints) as the _second_ type parameter to the `Agent` class definition.
+
+<TypeScriptExample>
+
+```ts
+import { Agent } from "@cloudflare/agents";
+
+interface Env {}
+
+//
+interface FlightRecord {
+	id: string;
+	departureIata: string;
+	arrival: Date;;
+	arrivalIata: string;
+	price: number;
+}
+
+// Pass in the type of your Agent's state
+export class MyAgent extends Agent<Env, FlightRecord> {
+  // This allows this.setState and
+}
+```
+
+</TypeScriptExample>
+
 ### Synchronizing state
 
 Clients can connect to an Agent and stay synchronized with its state using the React hooks provided as part of `@cloudflare/agents/react`:
@@ -78,4 +106,27 @@ Common use cases:
 * Multi-window/tab synchronization
 * Live updates across multiple devices
 * Maintaining consistent UI state across clients
-* When new clients connect, they automatically receive the current state from the agent, ensuring all clients start with the latest data.
+* When new clients connect, they automatically receive the current state from the agent, ensuring all clients start with the latest data.
+
+### SQL API
+
+Every individual Agent instance has its own SQL (SQLite) database that runs _within the same context_ as the Agent itself. This means that inserting or querying data within your Agent is effectively zero-latency: the Agent doesn't have to round-trip across a continent or the world to access its own data.
+
+TODO
+
+<TypeScriptExample>
+
+```ts
+
+
+```
+
+</TypeScriptExample>
+
+:::note
+
+Learn more about the zero-latency SQL storage that powers both Agents and Durable Objects [on our blog](https://blog.cloudflare.com/sqlite-in-durable-objects/).
+
+:::
+
+The SQL API exposed to an Agent is identical to the one [within by Durable Objects](/durable-objects/api/sql-storage/). This means that you can use the same SQL queries and commands to interact with the Agent's database.