Build Agents on Cloudflare

Agents are systems that use AI models to make decisions and execute tasks autonomously. They integrate with external APIs, execute custom functions, and maintain access to your data sources to handle complex workflows.

Think of agents as digital assistants with persistent context, they remember previous interactions, maintain consistent behavior patterns, and have access to specific tools and capabilities for their designated roles.

Built on Cloudflare's infrastructure, agents are stateful classes that run on Durable Objects. They handle HTTP requests, WebSocket connections, task scheduling, AI model integration and more.

Ship your first Agent

To use the Agent starter template and create your first Agent with the Agents SDK:

Create a new project:

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

Install dependencies:

npm install

Set up your environment:

Create a .dev.vars file:

OPENAI_API_KEY=your_openai_api_key

Run locally:

npm start

Deploy:

npm run deploy

Head to the guide on building a chat agent to learn how the starter project is built and how to use it as a foundation for your own agents.

If you are already building on Workers, you can install the agents package directly into an existing project:

npm i agents

And then define your first Agent by creating a class that extends the Agent class:

JavaScript
TypeScript

import { Agent } from "agents";

export class MyAgent extends Agent {
  // Define methods on the Agent:
  // https://developers.cloudflare.com/agents/api-reference/agents-api/
  //
  // Every Agent has built in state via this.setState and this.sql
  // Built-in scheduling via this.schedule
  // Agents support WebSockets, HTTP requests, state synchronization and
  // can run for seconds, minutes or hours: as long as the tasks need.
}

import { Agent } from "agents";

export class MyAgent extends Agent {
  // Define methods on the Agent:
  // https://developers.cloudflare.com/agents/api-reference/agents-api/
  //
  // Every Agent has built in state via this.setState and this.sql
  // Built-in scheduling via this.schedule
  // Agents support WebSockets, HTTP requests, state synchronization and
  // can run for seconds, minutes or hours: as long as the tasks need.
}

Lastly, add the Durable Objects binding to your wrangler file:

wrangler.jsonc
wrangler.toml

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

[[durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "MyAgent" ]

Dive into the Agent SDK reference to learn more about how to use the Agents SDK package and defining an Agent.

Why build agents on Cloudflare?

We built the Agents SDK with a few things in mind:

Batteries (state) included: Agents come with built-in state management, with the ability to automatically sync state between an Agent and clients, trigger events on state changes, and read+write to each Agent's SQL database.
Communicative: You can connect to an Agent via WebSockets and stream updates back to client in real-time. Handle a long-running response from a reasoning model, the results of an asynchronous workflow, or build a chat app that builds on the useAgent hook included in the Agents SDK.
Extensible: Agents are code. Use the AI models you want, bring-your-own headless browser service, pull data from your database hosted in another cloud, add your own methods to your Agent and call them.

Agents built with Agents SDK can be deployed directly to Cloudflare and run on top of Durable Objects — which you can think of as stateful micro-servers that can scale to tens of millions — and are able to run wherever they need to. Run your Agents close to a user for low-latency interactivity, close to your data for throughput, and/or anywhere in between.

Build on the Cloudflare Platform

Workers

Build serverless applications and deploy instantly across the globe for exceptional performance, reliability, and scale.

AI Gateway

Observe and control your AI applications with caching, rate limiting, request retries, model fallback, and more.

Vectorize

Build full-stack AI applications with Vectorize, Cloudflare's vector database. Adding Vectorize enables you to perform tasks such as semantic search, recommendations, anomaly detection or can be used to provide context and memory to an LLM.

Workers AI

Run machine learning models, powered by serverless GPUs, on Cloudflare's global network.

Workflows

Build stateful agents that guarantee executions, including automatic retries, persistent state that runs for minutes, hours, days, or weeks.