agents-sdk

Cloudflare Agents SDK

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

FIRST: Verify Installation

npm install agents

Agents require a binding in wrangler.jsonc:

{
  "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 });

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