Cloudflare Agents Starter

To deploy your agent to the Cloudflare global network, run:

npm run deploy

Once deployed, your agent's messages are persisted in SQLite, streams can resume upon reconnection, and the agent will automatically hibernate when idle.

To create and run a new AI agent project using this template, follow these steps:

1. Scaffold the project using the Cloudflare CLI:

npx create-cloudflare@latest --template cloudflare/agents-starter

2. Navigate to the directory and install dependencies:

cd agents-starter
npm install

3. Start the local development server:

npm run dev

Important: Authentication Requirements This template uses Workers AI with "ai": { "remote": true } in wrangler.jsonc. Because there is no local simulator for Workers AI, npm run dev opens a remote proxy session. You must be authenticated with Cloudflare. You can either:

• Run wrangler login in your terminal.
• Set a CLOUDFLARE_API_TOKEN environment variable (e.g., in a .env file).

Once running, access the agent at http://localhost:5173.

When a scheduled task is triggered, the executeTask method runs on the server. To perform work and notify connected clients without polluting the chat history, use this.broadcast() instead of saveMessages().

Using this.broadcast() sends a one-off event that the client can display (e.g., as a toast notification) without the AI seeing the notification as new context, which prevents infinite loops.

async executeTask(description: string, task: Schedule<string>) {
  // Do the actual work
  await sendEmail({ to: "user@example.com", subject: description });

  // Notify connected clients
  this.broadcast(
    JSON.stringify({ type: "scheduled-task", description, timestamp: new Date().toISOString() })
  );
}

The ChatAgent provides built-in scheduling capabilities. You can schedule tasks using the this.schedule(input, taskName, description, options) method.

• Scheduling a task: Use this.schedule(input, "executeTask", description, { idempotent: true }). The input can be a date, a delay in seconds, or a cron expression.
• Executing a task: Define a method (e.g., executeTask) that matches the name used in this.schedule. This method is called when the scheduled time arrives.
• Communicating results: Use this.broadcast(payload) inside your task execution method to notify connected clients without injecting the notification into the chat history (which prevents infinite loops).
• Managing tasks: Use tools like getScheduledTasks (to list tasks) and cancelScheduledTask (to cancel by ID) to give the AI control over the schedule.

Tools allow your agent to perform actions. In onChatMessage, you define a tools object passed to streamText. There are three main types of tools:

1. Server-side tools: Tools with an execute function that runs on the server (e.g., calling a weather API).
2. Client-side tools: Tools without an execute function. The browser handles the execution (e.g., getting a user's timezone).
3. Approval tools: Tools that include a needsApproval function. The agent will request user confirmation before running execute if the condition is met (e.g., math operations with large numbers).

You can also spread this.mcp.getAITools() into your tools object to include tools provided by connected MCP servers.

You can integrate external tools from Model Context Protocol (MCP) servers within the onChatMessage lifecycle method of your agent.

async onChatMessage(onFinish, options) {
  // Connect to an MCP server
  await this.mcp.connect("https://my-mcp-server.example/sse");

  const result = streamText({
    // ...
    tools: {
      ...myTools,
      ...this.mcp.getAITools() // Include MCP tools
    }
  });
}

You can expose agent methods as typed RPC (Remote Procedure Call) that your client can call directly using the @callable() decorator. This allows the client to trigger specific logic on the agent instance.

Server-side implementation:

import { callable } from "agents";

export class ChatAgent extends AIChatAgent<Env> {
  @callable()
  async getStats() {
    return { messageCount: this.messages.length };
  }
}

Client-side invocation:

const stats = await agent.call("getStats");

import { callable } from "agents";

export class ChatAgent extends AIChatAgent<Env> {
  @callable()
  async getStats() {
    return { messageCount: this.messages.length };
  }
}

// Client-side:
const stats = await agent.call("getStats");

You can manage Model Context Protocol (MCP) servers by calling these methods on your ChatAgent instance. These are decorated with @callable(), making them accessible via the agent's API:

• addServer(name: string, url: string): Adds a new MCP server.
• removeServer(serverId: string): Removes an existing MCP server by its ID.

@callable()
  async addServer(name: string, url: string) {
    return await this.addMcpServer(name, url);
  }

  @callable()
  async removeServer(serverId: string) {
    await this.removeMcpServer(serverId);
  }

The project exports a default handler for Cloudflare Workers. The fetch handler uses routeAgentRequest(request, env) to route incoming requests to the appropriate agent logic. This is the standard entry point for deploying the agent to a Cloudflare Worker environment.

export default {
  async fetch(request: Request, env: Env) {
    return (
      (await routeAgentRequest(request, env)) ||
      new Response("Not found", { status: 404 })
    );
  }
} satisfies ExportedHandler<Env>;