Cloudflare Agents SDK
Cloudflare Agents SDK enables building AI-powered agents on Durable Objects with state, WebSockets, SQL, scheduling, and AI integration.
Core Value
Build stateful, globally distributed AI agents with persistent memory, real-time connections, scheduled tasks, and async workflows.
When to Use
- Persistent state + memory required
- Real-time WebSocket connections
- Long-running workflows (minutes/hours)
- Chat interfaces with AI models
- Scheduled/recurring tasks with state
- DB queries with agent state
What Type of Agent?
| Use Case | Class | Key Features |
|---|---|---|
| AI chat interface | AIChatAgent |
Auto-streaming, tools, message history, resumable |
| MCP tool provider | Agent + MCP |
Expose tools to AI systems |
| Custom logic/routing | Agent |
Full control, WebSockets, email, SQL |
| Real-time collaboration | Agent |
WebSocket state, broadcasts |
| Email processing | Agent |
onEmail() handler |
Quick Start
AI Chat Agent:
import { AIChatAgent } from "agents";
import { openai } from "@ai-sdk/openai";
export class ChatAgent extends AIChatAgent<Env> {
async onChatMessage(onFinish) {
return this.streamText({
model: openai("gpt-4"),
messages: this.messages,
onFinish,
});
}
}Base Agent:
import { Agent } from "agents";
export class MyAgent extends Agent<Env> {
onStart() {
this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY)`;
}
async onRequest(request: Request) {
return Response.json({ state: this.state });
}
}Reading Order
| Task | Files to Read |
|---|---|
| Quick start | README only |
| Build chat agent | README → api.md (AIChatAgent) → patterns.md |
| Setup project | README → configuration.md |
| Add React frontend | README → api.md (Client Hooks) → patterns.md |
| Build MCP server | api.md (MCP) → patterns.md |
| Background tasks | api.md (Scheduling, Task Queue) → patterns.md |
| Debug issues | gotchas.md |
Package Entry Points
| Import | Purpose |
|---|---|
agents |
Server-side Agent classes, lifecycle |
agents/react |
useAgent() hook for WebSocket connections |
agents/ai-react |
useAgentChat() hook for AI chat UIs |
In This Reference
- configuration.md - SDK setup, wrangler config, routing
- api.md - Agent classes, lifecycle, client hooks
- patterns.md - Common workflows, best practices
- gotchas.md - Common issues, limits
See Also
- durable-objects - Agent infrastructure
- d1 - External database integration
- workers-ai - AI model integration
- vectorize - Vector search for RAG patterns