{
  "durable_objects": {
    // "class_name" must match your Agent class name exactly
    "bindings": [{ "name": "Counter", "class_name": "Counter" }]
  },
  "migrations": [
    // Required: list all Agent classes for SQLite storage
    { "tag": "v1", "new_sqlite_classes": ["Counter"] }
  ]
}

Choosing an Agent Type

Use Case	Base Class	Package
Custom state + RPC, no chat	`Agent`	`agents`
Chat with message persistence	`AIChatAgent`	`@cloudflare/ai-chat`
Building an MCP server	`McpAgent`	`agents/mcp`

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

Task	API
Persist state	`this.setState({ count: 1 })`
Read state	`this.state.count`
Schedule task	`this.schedule(60, "taskMethod", payload)`
Schedule cron	`this.schedule("0 * * * *", "hourlyTask")`
Cancel schedule	`this.cancelSchedule(id)`
Queue task	`this.queue("processItem", payload)`
SQL query	this.sql`SELECT * FROM users WHERE id = ${id}`
RPC method	`@callable() async myMethod() { ... }`
Streaming RPC	`@callable({ streaming: true }) async stream(res) { ... }`

Minimal Agent

import { Agent, routeAgentRequest, callable } from "agents";

type State = { count: number };

export class Counter extends Agent<Env, State> {
  initialState = { count: 0 };

  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }
}

export default {
  fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
};

Streaming Chat Agent

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

Install additional dependencies first:

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

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

{
  "durable_objects": {
    "bindings": [{ "name": "Chat", "class_name": "Chat" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Chat"] }]
}

import { AIChatAgent } from "@cloudflare/ai-chat";
import { routeAgentRequest } from "agents";
import { streamText, convertToModelMessages } from "ai";
import { openai } from "@ai-sdk/openai";

export class Chat extends AIChatAgent<Env> {
  async onChatMessage(onFinish) {
    const result = streamText({
      model: openai("gpt-4o"),
      messages: await convertToModelMessages(this.messages),
      onFinish
    });
    return result.toUIMessageStreamResponse();
  }
}

export default {
  fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
};

Client (React):

import { useAgent } from "agents/react";
import { useAgentChat } from "@cloudflare/ai-chat/react";

const agent = useAgent({ agent: "Chat", name: "my-chat" });
const { messages, input, handleSubmit } = useAgentChat({ agent });

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

Best Practices

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

cloudflare-agents-sdk

Cloudflare Agents SDK

FIRST: Verify Installation