WebSockets

import { TypeScriptExample, LinkCard } from "~/components";

The Agent class installs the WebSockets capability and calls your onConnect(), onMessage(), onClose(), and onError() methods. Connections hibernate when idle, and useAgent and AgentClient from the client SDK connect to it. This page covers the Agent methods. For connection state, tags, readonly connections, and transports, refer to the WebSockets capability.

Handle connections

import {
	Agent,
	type Connection,
	type ConnectionContext,
	type WSMessage,
} from "agents";

export class ChatAgent extends Agent<Env> {
	getConnectionTags(_connection: Connection, ctx: ConnectionContext): string[] {
		const room = new URL(ctx.request.url).searchParams.get("room");
		return room ? [`room:${room}`] : [];
	}

	onConnect(connection: Connection, ctx: ConnectionContext) {
		connection.setState({ joinedAt: Date.now() });
		connection.send(JSON.stringify({ type: "welcome", id: connection.id }));
	}

	onMessage(connection: Connection, message: WSMessage) {
		// Send to everyone except the sender.
		this.broadcast(String(message), [connection.id]);
	}

	onClose(connection: Connection) {
		this.broadcast(JSON.stringify({ type: "left", id: connection.id }));
	}
}

Route requests to the Agent with routeAgentRequest(), and check who is calling first. For more information, refer to Authentication.

Agent methods

These methods map to the WebSockets capability's handlers and options. For the Connection object, refer to Connections.

Hibernation

An idle Agent hibernates while its WebSocket connections stay open. A message wakes it, and onMessage() runs as usual. Keep anything you need after a wake in this.state, connection.state, or SQLite, not in class fields. To keep the Agent in memory instead, set static options = { hibernate: false }.

Next steps