Cloudflare Agents SDK

Build persistent, stateful AI agents on Cloudflare Workers using the agents npm package.

FIRST: Verify Installation

bash
1npm install agents

Agents require a binding in wrangler.jsonc:

jsonc
1{
2  "durable_objects": {
3    // "class_name" must match your Agent class name exactly
4    "bindings": [{ "name": "Counter", "class_name": "Counter" }]
5  },
6  "migrations": [
7    // Required: list all Agent classes for SQLite storage
8    { "tag": "v1", "new_sqlite_classes": ["Counter"] }
9  ]
10}

Choosing an Agent Type

Key Concepts

• Agent base class provides state, scheduling, RPC, MCP, and email capabilities
• AIChatAgent adds streaming chat with automatic message persistence and resumable streams
• Code Mode generates executable code instead of tool calls—reduces token usage significantly
• this.state / this.setState() - automatic persistence to SQLite, broadcasts to clients
• this.schedule() - schedule tasks at Date, delay (seconds), or cron expression
• @callable decorator - expose methods to clients via WebSocket RPC

Quick Reference

Minimal Agent

typescript
1import { Agent, routeAgentRequest, callable } from "agents";
2
3type State = { count: number };
4
5export class Counter extends Agent<Env, State> {
6  initialState = { count: 0 };
7
8  @callable()
9  increment() {
10    this.setState({ count: this.state.count + 1 });
11    return this.state.count;
12  }
13}
14
15export default {
16  fetch: (req, env) =>
17    routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
18};

Streaming Chat Agent

Use AIChatAgent for chat with automatic message persistence and resumable streaming.

Install additional dependencies first:

bash
1npm install @cloudflare/ai-chat ai @ai-sdk/openai

Add wrangler.jsonc config (same pattern as base Agent):

jsonc
1{
2  "durable_objects": {
3    "bindings": [{ "name": "Chat", "class_name": "Chat" }]
4  },
5  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Chat"] }]
6}

typescript
1import { AIChatAgent } from "@cloudflare/ai-chat";
2import { routeAgentRequest } from "agents";
3import { streamText, convertToModelMessages } from "ai";
4import { openai } from "@ai-sdk/openai";
5
6export class Chat extends AIChatAgent<Env> {
7  async onChatMessage(onFinish) {
8    const result = streamText({
9      model: openai("gpt-4o"),
10      messages: await convertToModelMessages(this.messages),
11      onFinish
12    });
13    return result.toUIMessageStreamResponse();
14  }
15}
16
17export default {
18  fetch: (req, env) =>
19    routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
20};

Client (React):

tsx
1import { useAgent } from "agents/react";
2import { useAgentChat } from "@cloudflare/ai-chat/react";
3
4const agent = useAgent({ agent: "Chat", name: "my-chat" });
5const { messages, input, handleSubmit } = useAgentChat({ agent });

Detailed References

• references/state-scheduling.md - State persistence, scheduling, queues
• references/streaming-chat.md - AIChatAgent, resumable streams, UI patterns
• references/codemode.md - Generate code instead of tool calls (token savings)
• references/mcp.md - MCP server integration
• references/email.md - Email routing and handling

When to Use Code Mode

Code Mode generates executable JavaScript instead of making individual tool calls. Use it when:

• Chaining multiple tool calls in sequence
• Complex conditional logic across tools
• MCP server orchestration (multiple servers)
• Token budget is constrained

See references/codemode.md for setup and examples.

Best Practices

1. Prefer streaming: Use streamText and toUIMessageStreamResponse() for chat
2. Use AIChatAgent for chat: Handles message persistence and resumable streams automatically
3. Type your state: Agent<Env, State> ensures type safety for this.state
4. Use @callable for RPC: Cleaner than manual WebSocket message handling
5. Code Mode for complex workflows: Reduces round-trips and token usage
6. Schedule vs Queue: Use schedule() for time-based, queue() for sequential processing