Building AI Agent On Cloudflare

1---
2name: building-ai-agent-on-cloudflare
3description: |
4  Builds AI agents on Cloudflare using the Agents SDK with state management,
5  real-time WebSockets, scheduled tasks, tool integration, and chat capabilities.
6  Generates production-ready agent code deployed to Workers.
7 
8  Use when: user wants to "build an agent", "AI agent", "chat agent", "stateful
9  agent", mentions "Agents SDK", needs "real-time AI", "WebSocket AI", or asks
10  about agent "state management", "scheduled tasks", or "tool calling".
11---
12 
13# Building Cloudflare Agents
14 
15Creates AI-powered agents using Cloudflare's Agents SDK with persistent state, real-time communication, and tool integration.
16 
17## When to Use
18 
19- User wants to build an AI agent or chatbot
20- User needs stateful, real-time AI interactions
21- User asks about the Cloudflare Agents SDK
22- User wants scheduled tasks or background AI work
23- User needs WebSocket-based AI communication
24 
25## Prerequisites
26 
27- Cloudflare account with Workers enabled
28- Node.js 18+ and npm/pnpm/yarn
29- Wrangler CLI (`npm install -g wrangler`)
30 
31## Quick Start
32 
33```bash
34npm create cloudflare@latest -- my-agent --template=cloudflare/agents-starter
35cd my-agent
36npm start
37```
38 
39Agent runs at `http://localhost:8787`
40 
41## Core Concepts
42 
43### What is an Agent?
44 
45An Agent is a stateful, persistent AI service that:
46- Maintains state across requests and reconnections
47- Communicates via WebSockets or HTTP
48- Runs on Cloudflare's edge via Durable Objects
49- Can schedule tasks and call tools
50- Scales horizontally (each user/session gets own instance)
51 
52### Agent Lifecycle
53 
54```
55Client connects → Agent.onConnect() → Agent processes messages
56                                    → Agent.onMessage()
57                                    → Agent.setState() (persists + syncs)
58Client disconnects → State persists → Client reconnects → State restored
59```
60 
61## Basic Agent Structure
62 
63```typescript
64import { Agent, Connection } from "agents";
65 
66interface Env {
67  AI: Ai;  // Workers AI binding
68}
69 
70interface State {
71  messages: Array<{ role: string; content: string }>;
72  preferences: Record<string, string>;
73}
74 
75export class MyAgent extends Agent<Env, State> {
76  // Initial state for new instances
77  initialState: State = {
78    messages: [],
79    preferences: {},
80  };
81 
82  // Called when agent starts or resumes
83  async onStart() {
84    console.log("Agent started with state:", this.state);
85  }
86 
87  // Handle WebSocket connections
88  async onConnect(connection: Connection) {
89    connection.send(JSON.stringify({
90      type: "welcome",
91      history: this.state.messages,
92    }));
93  }
94 
95  // Handle incoming messages
96  async onMessage(connection: Connection, message: string) {
97    const data = JSON.parse(message);
98 
99    if (data.type === "chat") {
100      await this.handleChat(connection, data.content);
101    }
102  }
103 
104  // Handle disconnections
105  async onClose(connection: Connection) {
106    console.log("Client disconnected");
107  }
108 
109  // React to state changes
110  onStateUpdate(state: State, source: string) {
111    console.log("State updated by:", source);
112  }
113 
114  private async handleChat(connection: Connection, userMessage: string) {
115    // Add user message to history
116    const messages = [
117      ...this.state.messages,
118      { role: "user", content: userMessage },
119    ];
120 
121    // Call AI
122    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
123      messages,
124    });
125 
126    // Update state (persists and syncs to all clients)
127    this.setState({
128      ...this.state,
129      messages: [
130        ...messages,
131        { role: "assistant", content: response.response },
132      ],
133    });
134 
135    // Send response
136    connection.send(JSON.stringify({
137      type: "response",
138      content: response.response,
139    }));
140  }
141}
142```
143 
144## Entry Point Configuration
145 
146```typescript
147// src/index.ts
148import { routeAgentRequest } from "agents";
149import { MyAgent } from "./agent";
150 
151export default {
152  async fetch(request: Request, env: Env) {
153    // routeAgentRequest handles routing to /agents/:class/:name
154    return (
155      (await routeAgentRequest(request, env)) ||
156      new Response("Not found", { status: 404 })
157    );
158  },
159};
160 
161export { MyAgent };
162```
163 
164Clients connect via: `wss://my-agent.workers.dev/agents/MyAgent/session-id`
165 
166## Wrangler Configuration
167 
168```toml
169name = "my-agent"
170main = "src/index.ts"
171compatibility_date = "2024-12-01"
172 
173[ai]
174binding = "AI"
175 
176[durable_objects]
177bindings = [{ name = "AGENT", class_name = "MyAgent" }]
178 
179[[migrations]]
180tag = "v1"
181new_classes = ["MyAgent"]
182```
183 
184## State Management
185 
186### Reading State
187 
188```typescript
189// Current state is always available
190const currentMessages = this.state.messages;
191const userPrefs = this.state.preferences;
192```
193 
194### Updating State
195 
196```typescript
197// setState persists AND syncs to all connected clients
198this.setState({
199  ...this.state,
200  messages: [...this.state.messages, newMessage],
201});
202 
203// Partial updates work too
204this.setState({
205  preferences: { ...this.state.preferences, theme: "dark" },
206});
207```
208 
209### SQL Storage
210 
211For complex queries, use the embedded SQLite database:
212 
213```typescript
214// Create tables
215await this.sql`
216  CREATE TABLE IF NOT EXISTS documents (
217    id INTEGER PRIMARY KEY AUTOINCREMENT,
218    title TEXT NOT NULL,
219    content TEXT,
220    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
221  )
222`;
223 
224// Insert
225await this.sql`
226  INSERT INTO documents (title, content)
227  VALUES (${title}, ${content})
228`;
229 
230// Query
231const docs = await this.sql`
232  SELECT * FROM documents WHERE title LIKE ${`%${search}%`}
233`;
234```
235 
236## Scheduled Tasks
237 
238Agents can schedule future work:
239 
240```typescript
241async onMessage(connection: Connection, message: string) {
242  const data = JSON.parse(message);
243 
244  if (data.type === "schedule_reminder") {
245    // Schedule task for 1 hour from now
246    const { id } = await this.schedule(3600, "sendReminder", {
247      message: data.reminderText,
248      userId: data.userId,
249    });
250 
251    connection.send(JSON.stringify({ type: "scheduled", taskId: id }));
252  }
253}
254 
255// Called when scheduled task fires
256async sendReminder(data: { message: string; userId: string }) {
257  // Send notification, email, etc.
258  console.log(`Reminder for ${data.userId}: ${data.message}`);
259 
260  // Can also update state
261  this.setState({
262    ...this.state,
263    lastReminder: new Date().toISOString(),
264  });
265}
266```
267 
268### Schedule Options
269 
270```typescript
271// Delay in seconds
272await this.schedule(60, "taskMethod", { data });
273 
274// Specific date
275await this.schedule(new Date("2025-01-01T00:00:00Z"), "taskMethod", { data });
276 
277// Cron expression (recurring)
278await this.schedule("0 9 * * *", "dailyTask", {});  // 9 AM daily
279await this.schedule("*/5 * * * *", "everyFiveMinutes", {});  // Every 5 min
280 
281// Manage schedules
282const schedules = await this.getSchedules();
283await this.cancelSchedule(taskId);
284```
285 
286## Chat Agent (AI-Powered)
287 
288For chat-focused agents, extend `AIChatAgent`:
289 
290```typescript
291import { AIChatAgent } from "agents/ai-chat-agent";
292 
293export class ChatBot extends AIChatAgent<Env> {
294  // Called for each user message
295  async onChatMessage(message: string) {
296    const response = await this.env.AI.run("@cf/meta/llama-3-8b-instruct", {
297      messages: [
298        { role: "system", content: "You are a helpful assistant." },
299        ...this.messages,  // Automatic history management
300        { role: "user", content: message },
301      ],
302      stream: true,
303    });
304 
305    // Stream response back to client
306    return response;
307  }
308}
309```
310 
311Features included:
312- Automatic message history
313- Resumable streaming (survives disconnects)
314- Built-in `saveMessages()` for persistence
315 
316## Client Integration
317 
318### React Hook
319 
320```tsx
321import { useAgent } from "agents/react";
322 
323function Chat() {
324  const { state, send, connected } = useAgent({
325    agent: "my-agent",
326    name: userId,  // Agent instance ID
327  });
328 
329  const sendMessage = (text: string) => {
330    send(JSON.stringify({ type: "chat", content: text }));
331  };
332 
333  return (
334    <div>
335      {state.messages.map((msg, i) => (
336        <div key={i}>{msg.role}: {msg.content}</div>
337      ))}
338      <input onKeyDown={(e) => e.key === "Enter" && sendMessage(e.target.value)} />
339    </div>
340  );
341}
342```
343 
344### Vanilla JavaScript
345 
346```javascript
347const ws = new WebSocket("wss://my-agent.workers.dev/agents/MyAgent/user123");
348 
349ws.onopen = () => {
350  console.log("Connected to agent");
351};
352 
353ws.onmessage = (event) => {
354  const data = JSON.parse(event.data);
355  console.log("Received:", data);
356};
357 
358ws.send(JSON.stringify({ type: "chat", content: "Hello!" }));
359```
360 
361## Common Patterns
362 
363See [references/agent-patterns.md](references/agent-patterns.md) for:
364- Tool calling and function execution
365- Multi-agent orchestration
366- RAG (Retrieval Augmented Generation)
367- Human-in-the-loop workflows
368 
369## Deployment
370 
371```bash
372# Deploy
373npx wrangler deploy
374 
375# View logs
376wrangler tail
377 
378# Test endpoint
379curl https://my-agent.workers.dev/agents/MyAgent/test-user
380```
381 
382## Troubleshooting
383 
384See [references/troubleshooting.md](references/troubleshooting.md) for common issues.
385 
386## References
387 
388- [references/examples.md](references/examples.md) — Official templates and production examples
389- [references/agent-patterns.md](references/agent-patterns.md) — Advanced patterns
390- [references/state-patterns.md](references/state-patterns.md) — State management strategies
391- [references/troubleshooting.md](references/troubleshooting.md) — Error solutions
392