websockets

Author: elithrar

src/content/docs/agents/examples/browse-the-web.mdx

@@ -38,9 +38,13 @@ npm install @cloudflare/puppeteer --save-dev
 <WranglerConfig>
 
 ```jsonc
-"browser": {
+{
+	// ...
+	"browser": {
     "binding": "MYBROWSER"
-  },
+  }
+  // ...
+}
 ```
 
 </WranglerConfig>

src/content/docs/agents/examples/schedule-tasks.mdx

@@ -9,26 +9,48 @@ import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/com
 
 An Agent can schedule tasks to be run in the future by calling `this.schedule(when, callback, data)`, where `when` can be a delay, a `Date`, or a cron string; `callback` the function name to call, and `data` is an object of data to pass to the function.
 
-Scheduled tasks can do anything a request or message from a user can: make requests, query databases, send emails, read+write state, etc.
+Scheduled tasks can do anything a request or message from a user can: make requests, query databases, send emails, read+write state: scheduled tasks can invoke any regular method on your Agent.
 
 ### Scheduling tasks
 
-You can call `this.schedule` within any method on an Agent, and schedule tens-of-thousands of tasks per individual Agent.
+You can call `this.schedule` within any method on an Agent, and schedule tens-of-thousands of tasks per individual Agent:
+
+```ts
+import { Agent } from "@cloudflare/agents"
+
+export class SchedulingAgent extends Agent {
+	async onRequest(request) {
+		// Handle an incoming request
+		// Schedule a task 5 minutes from now
+		// Calls the "checkFlights" method
+		let { taskId } = await this.schedule(600, "checkFlights", { flight: "DL264", date: "2025-02-23" });
+		return Response.json({ taskId });
+	}
+
+	async checkFlights(data) {
+		// Invoked when our scheduled task runs
+		// We can also call this.schedule here to schedule another task
+	}
+}
+```
+</TypeScriptExample>
+
+You can schedule tasks in multiple ways:
 
 <TypeScriptExample>
 
 ```ts
 // schedule a task to run in 10 seconds
-let task = await this.schedule(10, "myTask", { message: "hello" });
+let task = await this.schedule(10, "someTask", { message: "hello" });
 
 // schedule a task to run at a specific date
-let task = await this.schedule(new Date("2025-01-01"), "myTask", { message: "hello" });
+let task = await this.schedule(new Date("2025-01-01"), "someTask", {});
 
 // schedule a task to run every 10 seconds
-let { id } = await this.schedule("*/10 * * * *", "myTask", { message: "hello" });
+let { id } = await this.schedule("*/10 * * * *", "someTask", { message: "hello" });
 
 // schedule a task to run every 10 seconds, but only on Mondays
-let task = await this.schedule("0 0 * * 1", "myTask", { message: "hello" });
+let task = await this.schedule("0 0 * * 1", "someTask", { message: "hello" });
 
 // cancel a scheduled task
 this.cancelSchedule(task.id);

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

@@ -8,4 +8,143 @@ sidebar:
 
 import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
 
-TODO
+Users and clients can connect to an Agent directly over WebSockets, allowing long-running, bi-directional communication with your Agent as it operates.
+
+To enable an Agent to accept WebSockets, define `onConnect` and `onMessage` methods on your Agent.
+
+* `onConnect(connection: Connection, ctx: ConnectionContext)` is called when a client establishes a new WebSocket connection. The original HTTP request, including request headers, cookies and the URL itself, are available on `ctx.request`.
+* `onMessage(connection: Connection, message: WSMessage)` is called for each incoming WebSocket message. Messages are one of `ArrayBuffer | ArrayBufferView | string`, and you can send messages back to a client using `connection.send()`. You can distinguish between client connections by checking `connection.id`, which is unique for each connected client.
+
+Here's an example of an Agent that echoes back any message it receives:
+
+<TypeScriptExample>
+
+```ts
+import { Agent, Connection } from "@cloudflare/agents";
+
+export class ChatAgent extends Agent {
+  async onConnect(connection: Connection, ctx: ConnectionContext) {
+  	// Access the request to verify any authentication tokens
+    // provided in headers or cookies
+    let token = ctx.request.headers.get("Authorization");
+    if (!token) {
+      await connection.close(4000, "Unauthorized");
+      return;
+    }
+
+		// Handle auth using your favorite library and/or auth scheme:
+ 		// try {
+		// 	 await jwt.verify(token, env.JWT_SECRET);
+		// } catch (error) {
+		// 	 connection.close(4000, 'Invalid Authorization header');
+		// 	 return;
+		// }
+
+		// Accept valid connections
+  	connection.accept()
+  }
+
+  async onMessage(connection: Connection, message: WSMessage) {
+    // const response = await longRunningAITask(message)
+    await connection.send(message)
+  }
+}
+```
+
+</TypeScriptExample>
+
+## Connecting clients
+
+The Agent framework includes a useful helper package for connecting directly to your agent (or other agents) from a client application. Import `@cloudflare/agents/client`, create an instance of `AgentClient` and use it to connect to an instance of your Agent:
+
+<TypeScriptExample>
+
+```ts
+import { AgentClient } from "@cloudflare/agents/client";
+
+const connection = new AgentClient({
+  agent: "dialogue-agent",
+  name: "insight-seeker",
+});
+
+connection.addEventListener("message", (event) => {
+  console.log("Received:", event.data);
+});
+
+connection.send(
+  JSON.stringify({
+    type: "inquiry",
+    content: "What patterns do you see?",
+  })
+);
+```
+
+</TypeScriptExample>
+
+## React clients
+
+React-based applications can import `@cloudflare/agents/react` and use the `useAgent` hook to connect to an instance of an Agent directly:
+
+<TypeScriptExample>
+
+```ts
+import { useAgent } from "@cloudflare/agents/react";
+
+function AgentInterface() {
+  const connection = useAgent({
+    agent: "dialogue-agent",
+    name: "insight-seeker",
+    onMessage: (message) => {
+      console.log("Understanding received:", message.data);
+    },
+    onOpen: () => console.log("Connection established"),
+    onClose: () => console.log("Connection closed"),
+  });
+
+  const inquire = () => {
+    connection.send(
+      JSON.stringify({
+        type: "inquiry",
+        content: "What insights have you gathered?",
+      })
+    );
+  };
+
+  return (
+    <div className="agent-interface">
+      <button onClick={inquire}>Seek Understanding</button>
+    </div>
+  );
+}
+
+```
+</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/examples/manage-and-sync-state/) to automatically synchronize state across all clients connected to your agent.
+
+## Handling WebSocket events
+
+Define `onError` and `onClose` methods on your Agent to explicitly handle WebSocket client errors and close events. Log errors, clean up state, and/or emit metrics:
+
+<TypeScriptExample>
+
+```ts
+import { Agent, Connection } from "@cloudflare/agents";
+
+export class ChatAgent extends Agent {
+ 	// onConnect and onMessage methods
+  // ...
+
+  // 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();
+	}
+}
+
+```
+
+</TypeScriptExample>