1# Patterns & Use Cases
2 
3## AI Chat w/Tools
4 
5**Server (AIChatAgent):**
6 
7```ts
8import { AIChatAgent } from "@cloudflare/ai-chat";
9import { openai } from "@ai-sdk/openai";
10import { tool } from "ai";
11import { z } from "zod";
12 
13export class ChatAgent extends AIChatAgent<Env> {
14  async onChatMessage(onFinish) {
15    return this.streamText({
16      model: openai("gpt-4"),
17      messages: this.messages, // Auto-managed
18      tools: {
19        getWeather: tool({
20          description: "Get current weather",
21          parameters: z.object({ city: z.string() }),
22          execute: async ({ city }) => `Weather in ${city}: Sunny, 72°F`
23        }),
24        searchDocs: tool({
25          description: "Search documentation",
26          parameters: z.object({ query: z.string() }),
27          execute: async ({ query }) => JSON.stringify(
28            this.sql<{title, content}>`SELECT title, content FROM docs WHERE content LIKE ${'%' + query + '%'}`
29          )
30        })
31      },
32      onFinish,
33    });
34  }
35}
36```
37 
38**Client (React):**
39 
40```tsx
41import { useAgent } from "agents/react";
42import { useAgentChat } from "@cloudflare/ai-chat/react";
43 
44function ChatUI() {
45  const agent = useAgent({ agent: "ChatAgent" });
46  const { messages, input, handleInputChange, handleSubmit, isLoading } = useAgentChat({ agent });
47  
48  return (
49    <div>
50      {messages.map(m => <div key={m.id}>{m.role}: {m.content}</div>)}
51      <form onSubmit={handleSubmit}>
52        <input value={input} onChange={handleInputChange} disabled={isLoading} />
53        <button disabled={isLoading}>Send</button>
54      </form>
55    </div>
56  );
57}
58```
59 
60## Human-in-the-Loop (Client Tools)
61 
62Server defines tool, client executes:
63 
64```ts
65// Server
66export class ChatAgent extends AIChatAgent<Env> {
67  async onChatMessage(onFinish) {
68    return this.streamText({
69      model: openai("gpt-4"),
70      messages: this.messages,
71      tools: {
72        confirmAction: tool({
73          description: "Ask user to confirm",
74          parameters: z.object({ action: z.string() }),
75          execute: "client", // Client-side execution
76        })
77      },
78      onFinish,
79    });
80  }
81}
82 
83// Client
84const { messages } = useAgentChat({
85  agent,
86  onToolCall: async (toolCall) => {
87    if (toolCall.toolName === "confirmAction") {
88      return { confirmed: window.confirm(`Confirm: ${toolCall.args.action}?`) };
89    }
90  }
91});
92```
93 
94## Task Queue & Scheduled Processing
95 
96```ts
97export class TaskAgent extends Agent<Env> {
98  onStart() { 
99    this.schedule("*/5 * * * *", "processQueue", {}); // Every 5 min
100    this.schedule("0 0 * * *", "dailyCleanup", {}); // Daily
101  }
102  
103  async onRequest(req: Request) {
104    await this.queue("processVideo", { videoId: (await req.json()).videoId });
105    return Response.json({ queued: true });
106  }
107  
108  async processQueue() {
109    const tasks = await this.dequeue(10);
110    for (const task of tasks) {
111      if (task.name === "processVideo") await this.processVideo(task.data.videoId);
112    }
113  }
114  
115  async dailyCleanup() {
116    this.sql`DELETE FROM logs WHERE created_at < ${Date.now() - 86400000}`;
117  }
118}
119```
120 
121## Manual WebSocket Chat
122 
123Custom protocols (non-AI):
124 
125```ts
126export class ChatAgent extends Agent<Env> {
127  async onConnect(conn: Connection, ctx: ConnectionContext) {
128    conn.accept();
129    conn.setState({userId: ctx.request.headers.get("X-User-ID") || "anon"});
130    conn.send(JSON.stringify({type: "history", messages: this.state.messages}));
131  }
132  
133  async onMessage(conn: Connection, msg: WSMessage) {
134    const newMsg = {userId: conn.state.userId, text: JSON.parse(msg as string).text, timestamp: Date.now()};
135    this.setState({messages: [...this.state.messages, newMsg]});
136    this.connections.forEach(c => c.send(JSON.stringify(newMsg)));
137  }
138}
139```
140 
141## Email Processing w/AI
142 
143```ts
144export class EmailAgent extends Agent<Env> {
145  async onEmail(email: AgentEmail) {
146    const [text, from, subject] = [await email.text(), email.from, email.headers.get("subject") || ""];
147    this.sql`INSERT INTO emails (from_addr, subject, body) VALUES (${from}, ${subject}, ${text})`;
148    
149    const { text: summary } = await generateText({
150      model: openai("gpt-4o-mini"), prompt: `Summarize: ${subject}\n\n${text}`
151    });
152    
153    this.connections.forEach(c => c.send(JSON.stringify({type: "new_email", from, summary})));
154    if (summary.includes("urgent")) await this.schedule(0, "sendAutoReply", { to: from });
155  }
156}
157```
158 
159## Real-time Collaboration
160 
161```ts
162export class GameAgent extends Agent<Env> {
163  initialState = { players: [], gameStarted: false };
164  
165  async onConnect(conn: Connection, ctx: ConnectionContext) {
166    conn.accept();
167    const playerId = ctx.request.headers.get("X-Player-ID") || crypto.randomUUID();
168    conn.setState({ playerId });
169    
170    const newPlayer = { id: playerId, score: 0 };
171    this.setState({...this.state, players: [...this.state.players, newPlayer]});
172    this.connections.forEach(c => c.send(JSON.stringify({type: "player_joined", player: newPlayer})));
173  }
174  
175  async onMessage(conn: Connection, msg: WSMessage) {
176    const m = JSON.parse(msg as string);
177    
178    if (m.type === "move") {
179      this.setState({
180        ...this.state,
181        players: this.state.players.map(p => p.id === conn.state.playerId ? {...p, score: p.score + m.points} : p)
182      });
183      this.connections.forEach(c => c.send(JSON.stringify({type: "player_moved", playerId: conn.state.playerId})));
184    }
185    
186    if (m.type === "start" && this.state.players.length >= 2) {
187      this.setState({...this.state, gameStarted: true});
188      this.connections.forEach(c => c.send(JSON.stringify({type: "game_started"})));
189    }
190  }
191}
192```
193