Agents API

This page provides an overview of the Agents SDK. For detailed documentation on each feature, refer to the linked reference pages.

The Agents SDK provides two main APIs:

An Agent is a class that extends the base Agent class:

import { Agent, routeAgentRequest } from "agents";

export class MyAgent extends Agent<Env, State> {
	// Your agent logic
}

export default {
	async fetch(request: Request, env: Env) {
		return (
			(await routeAgentRequest(request, env)) ||
			new Response("Not found", { status: 404 })
		);
	},
} satisfies ExportedHandler<Env>;

Each Agent can have millions of instances. Each instance is a separate micro-server that runs independently, allowing horizontal scaling. Instances are addressed by a unique identifier (user ID, email, ticket number, etc.).

flowchart TD
    A["onStart<br/>(instance wakes up)"] --> B["onRequest<br/>(HTTP)"]
    A --> C["onConnect<br/>(WebSocket)"]
    A --> D["onEmail"]
    C --> E["onMessage  send()<br/>onError (on failure)"]
    E --> F["onClose"]

Each Agent instance has an embedded SQLite database accessed via this.sql:

// Create tables
this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;

// Insert data
this.sql`INSERT INTO users (id, name) VALUES (${id}, ${name})`;

// Query data
const users = this.sql<User>`SELECT * FROM users WHERE id = ${id}`;

For state that needs to sync with clients, use the State API instead.

Module-level helper exports include agentTool() from agents/agent-tools, which converts a Think or AIChatAgent subclass into an AI SDK tool definition.

import { useAgent } from "agents/react";
import type { MyAgent } from "./server";

function App() {
	const agent = useAgent<MyAgent, State>({
		agent: "my-agent",
		name: "user-123",
	});

	// Call methods on the agent
	agent.stub.someMethod();

	// Update state (syncs to server and all clients)
	agent.setState({ count: 1 });
}

For AI chat applications, extend AIChatAgent instead of Agent:

import { AIChatAgent } from "@cloudflare/ai-chat";

class ChatAgent extends AIChatAgent {
	async onChatMessage(onFinish) {
		// this.messages contains the conversation history
		// Return a streaming response
	}
}

Features include:

• Built-in message persistence
• Automatic resumable streaming (reconnect mid-stream)
• Works with useAgentChat React hook

Refer to Build a chat agent for a complete tutorial.

Agents are accessed via URL patterns:

https://your-worker.workers.dev/agents/:agent-name/:instance-name

Use routeAgentRequest() in your Worker to route requests:

import { routeAgentRequest } from "agents";

export default {
	async fetch(request: Request, env: Env) {
		return (
			routeAgentRequest(request, env) ||
			new Response("Not found", { status: 404 })
		);
	},
} satisfies ExportedHandler<Env>;

Refer to Routing for custom paths, CORS, and instance naming patterns.

Quick start

Configuration

WebSockets

Build a chat agent