getting-started

Getting Started

Build AI agents that persist, think, and act. Agents run on Cloudflare's global network, maintain state across requests, and connect to clients in real-time via WebSockets.

What you'll build: A counter agent with persistent state that syncs to a React frontend in real-time.

Time: ~10 minutes

---

Create a New Project

npm create cloudflare@latest -- --template cloudflare/agents-starter
cd my-agent
npm install

This creates a project with:

• src/server.ts - Your agent code
• src/client.tsx - React frontend
• wrangler.jsonc - Cloudflare configuration
• tsconfig.json - Extends agents/tsconfig for correct decorator and module settings
• vite.config.ts - Includes the agents/vite plugin for decorator support

The starter template includes two SDK integrations that are required for @callable() decorators. If you are setting up a project manually, add both:

tsconfig.json — extends agents/tsconfig, which sets target: "ES2021" and other recommended options:

{
  "extends": "agents/tsconfig"
}

vite.config.ts — includes the agents() plugin, which handles TC39 decorator transforms (required because Vite 8's Oxc transpiler does not support them yet):

import { cloudflare } from "@cloudflare/vite-plugin";
import react from "@vitejs/plugin-react";
import agents from "agents/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [agents(), react(), cloudflare()]
});

Start the dev server:

npm run dev

Open http://localhost:5173 to see your agent in action.

---

Your First Agent

Let's build a simple counter agent from scratch. Replace src/server.ts:

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

// Define the state shape
type CounterState = {
  count: number;
};

// Create the agent
export class Counter extends Agent<Env, CounterState> {
  // Initial state for new instances
  initialState: CounterState = { count: 0 };

  // Methods marked with @callable can be called from the client
  @callable()
  increment() {
    this.setState({ count: this.state.count + 1 });
    return this.state.count;
  }

  @callable()
  decrement() {
    this.setState({ count: this.state.count - 1 });
    return this.state.count;
  }

  @callable()
  reset() {
    this.setState({ count: 0 });
  }
}

// Route requests to agents
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    return (
      (await routeAgentRequest(request, env)) ??
      new Response("Not found", { status: 404 })
    );
  }
};