1# API Reference
2 
3## Agent Classes
4 
5### AIChatAgent
6 
7For AI chat with auto-streaming, message history, tools, resumable streaming.
8 
9```ts
10import { AIChatAgent } from "@cloudflare/ai-chat";
11import { openai } from "@ai-sdk/openai";
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 message history
18      tools: {
19        getWeather: {
20          description: "Get weather",
21          parameters: z.object({ city: z.string() }),
22          execute: async ({ city }) => `Sunny, 72°F in ${city}`
23        }
24      },
25      onFinish, // Persist response to this.messages
26    });
27  }
28}
29```
30 
31### Agent (Base Class)
32 
33Full control for custom logic, WebSockets, email, and SQL.
34 
35```ts
36import { Agent } from "agents";
37 
38export class MyAgent extends Agent<Env, State> {
39  // Lifecycle methods below
40}
41```
42 
43**Type params:** `Agent<Env, State, ConnState>` - Env bindings, agent state, connection state
44 
45## Lifecycle Hooks
46 
47```ts
48onStart() { // Init/restart
49  this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT, name TEXT)`;
50}
51 
52async onRequest(req: Request) { // HTTP
53  const {pathname} = new URL(req.url);
54  if (pathname === "/users") return Response.json(this.sql<{id,name}>`SELECT * FROM users`);
55  return new Response("Not found", {status: 404});
56}
57 
58async onConnect(conn: Connection<ConnState>, ctx: ConnectionContext) { // WebSocket
59  conn.accept();
60  conn.setState({userId: ctx.request.headers.get("X-User-ID")});
61  conn.send(JSON.stringify({type: "connected", state: this.state}));
62}
63 
64async onMessage(conn: Connection<ConnState>, msg: WSMessage) { // WS messages
65  const m = JSON.parse(msg as string);
66  this.setState({messages: [...this.state.messages, m]});
67  this.connections.forEach(c => c.send(JSON.stringify(m)));
68}
69 
70async onEmail(email: AgentEmail) { // Email routing
71  this.sql`INSERT INTO emails (from_addr,subject,body) VALUES (${email.from},${email.headers.get("subject")},${await email.text()})`;
72}
73```
74 
75## State, SQL, Scheduling
76 
77```ts
78// State
79this.setState({count: 42}); // Auto-syncs
80this.setState({...this.state, count: this.state.count + 1});
81 
82// SQL (parameterized queries prevent injection)
83this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;
84this.sql`INSERT INTO users (id,name) VALUES (${userId},${name})`;
85const users = this.sql<{id,name}>`SELECT * FROM users WHERE id = ${userId}`;
86 
87// Scheduling
88await this.schedule(new Date("2026-12-25"), "sendGreeting", {msg:"Hi"}); // Date
89await this.schedule(60, "checkStatus", {}); // Delay (sec)
90await this.schedule("0 0 * * *", "dailyCleanup", {}); // Cron
91await this.cancelSchedule(scheduleId);
92```
93 
94## RPC Methods (@callable)
95 
96```ts
97import { Agent, callable } from "agents";
98 
99export class MyAgent extends Agent<Env> {
100  @callable()
101  async processTask(input: {text: string}): Promise<{result: string}> {
102    return { result: await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt: input.text}) };
103  }
104}
105// Client: const result = await agent.processTask({ text: "Hello" });
106// Must return JSON-serializable values
107```
108 
109## Connections & AI
110 
111```ts
112// Connections (type: Agent<Env, State, ConnState>)
113this.connections.forEach(c => c.send(JSON.stringify(msg))); // Broadcast
114conn.setState({userId:"123"}); conn.close(1000, "Goodbye");
115 
116// Workers AI
117const r = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt});
118 
119// Manual streaming (prefer AIChatAgent)
120const stream = await client.chat.completions.create({model: "gpt-4", messages, stream: true});
121for await (const chunk of stream) conn.send(JSON.stringify({chunk: chunk.choices[0].delta.content}));
122```
123 
124**Type-safe state:** `Agent<Env, State, ConnState>` - third param types `conn.state`
125 
126## MCP Integration
127 
128Model Context Protocol for exposing tools:
129 
130```ts
131// Register & use MCP server
132await this.mcp.registerServer("github", {
133  url: env.MCP_SERVER_URL,
134  auth: { type: "oauth", clientId: env.GITHUB_CLIENT_ID, clientSecret: env.GITHUB_CLIENT_SECRET }
135});
136const tools = await this.mcp.getAITools(["github"]);
137return this.streamText({ model: openai("gpt-4"), messages: this.messages, tools, onFinish });
138```
139 
140## Task Queue
141 
142```ts
143await this.queue("processVideo", { videoId: "abc123" }); // Add task
144const tasks = await this.dequeue(10); // Process up to 10
145```
146 
147## Context & Cleanup
148 
149```ts
150const agent = getCurrentAgent<MyAgent>(); // Get current instance
151async destroy() { /* cleanup before agent destroyed */ }
152```
153 
154## AI Integration
155 
156```ts
157// Workers AI
158const r = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt});
159 
160// Manual streaming (prefer AIChatAgent for auto-streaming)
161const stream = await client.chat.completions.create({model: "gpt-4", messages, stream: true});
162for await (const chunk of stream) {
163  if (chunk.choices[0]?.delta?.content) conn.send(JSON.stringify({chunk: chunk.choices[0].delta.content}));
164}
165```
166 
167## Client Hooks (React)
168 
169```ts
170// useAgent() - WebSocket connection + RPC
171import { useAgent } from "agents/react";
172const agent = useAgent({ agent: "MyAgent", name: "user-123" }); // name for idFromName
173const result = await agent.processTask({ text: "Hello" }); // Call @callable methods
174// agent.readyState: 0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED
175 
176// useAgentChat() - AI chat UI
177import { useAgentChat } from "@cloudflare/ai-chat/react";
178const agent = useAgent({ agent: "ChatAgent" });
179const { messages, input, handleInputChange, handleSubmit, isLoading, stop, clearHistory } = 
180  useAgentChat({ 
181    agent, 
182    maxSteps: 5,        // Max tool iterations
183    resume: true,       // Auto-resume on disconnect
184    onToolCall: async (toolCall) => {
185      // Client tools (human-in-the-loop)
186      if (toolCall.toolName === "confirm") return { ok: window.confirm("Proceed?") };
187    }
188  });
189// status: "ready" | "submitted" | "streaming" | "error"
190```
191