1# Cloudflare Agents SDK
2 
3Cloudflare Agents SDK enables building AI-powered agents on Durable Objects with state, WebSockets, SQL, scheduling, and AI integration.
4 
5## Core Value
6Build stateful, globally distributed AI agents with persistent memory, real-time connections, scheduled tasks, and async workflows.
7 
8## When to Use
9- Persistent state + memory required
10- Real-time WebSocket connections
11- Long-running workflows (minutes/hours)
12- Chat interfaces with AI models
13- Scheduled/recurring tasks with state
14- DB queries with agent state
15 
16## What Type of Agent?
17 
18| Use Case | Class | Key Features |
19|----------|-------|--------------|
20| AI chat interface | `AIChatAgent` | Auto-streaming, tools, message history, resumable |
21| MCP tool provider | `Agent` + MCP | Expose tools to AI systems |
22| Custom logic/routing | `Agent` | Full control, WebSockets, email, SQL |
23| Real-time collaboration | `Agent` | WebSocket state, broadcasts |
24| Email processing | `Agent` | `onEmail()` handler |
25 
26## Quick Start
27 
28**AI Chat Agent:**
29```typescript
30import { AIChatAgent } from "@cloudflare/ai-chat";
31import { openai } from "@ai-sdk/openai";
32 
33export class ChatAgent extends AIChatAgent<Env> {
34  async onChatMessage(onFinish) {
35    return this.streamText({
36      model: openai("gpt-4"),
37      messages: this.messages,
38      onFinish,
39    });
40  }
41}
42```
43 
44**Base Agent:**
45```typescript
46import { Agent } from "agents";
47 
48export class MyAgent extends Agent<Env> {
49  onStart() {
50    this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY)`;
51  }
52  
53  async onRequest(request: Request) {
54    return Response.json({ state: this.state });
55  }
56}
57```
58 
59## Reading Order
60 
61| Task | Files to Read |
62|------|---------------|
63| Quick start | README only |
64| Build chat agent | README → api.md (AIChatAgent) → patterns.md |
65| Setup project | README → configuration.md |
66| Add React frontend | README → api.md (Client Hooks) → patterns.md |
67| Build MCP server | api.md (MCP) → patterns.md |
68| Background tasks | api.md (Scheduling, Task Queue) → patterns.md |
69| Debug issues | gotchas.md |
70 
71## Package Entry Points
72 
73| Import | Purpose |
74|--------|---------|
75| `agents` | Server-side Agent classes, lifecycle |
76| `agents/react` | `useAgent()` hook for WebSocket connections |
77| `agents/ai-react` | `useAgentChat()` hook for AI chat UIs |
78 
79## In This Reference
80- [configuration.md](./configuration.md) - SDK setup, wrangler config, routing
81- [api.md](./api.md) - Agent classes, lifecycle, client hooks
82- [patterns.md](./patterns.md) - Common workflows, best practices
83- [gotchas.md](./gotchas.md) - Common issues, limits
84 
85## See Also
86- durable-objects - Agent infrastructure
87- d1 - External database integration
88- workers-ai - AI model integration
89- vectorize - Vector search for RAG patterns