Build AI Agents on Cloudflare: SDK, API Reference, and Step-by-Step Guides

Harness the power of AI with Cloudflare's Agents SDK. Build and deploy intelligent, autonomous agents with state management, real-time communication, and seamless integration with Cloudflare's global platform.

Introduction

The Agents SDK empowers you to create and deploy AI-powered agents capable of autonomously performing tasks, engaging with clients in real time, calling AI models, persisting state, scheduling tasks, running asynchronous workflows, browsing the web, querying data from your database, supporting human-in-the-loop interactions, and much more.

Key Features

• Autonomous Task Execution: Build agents that can independently complete tasks.
• Real-time Communication: Enable agents to interact with clients in real time.
• AI Model Integration: Seamlessly integrate with various AI models.
• State Management: 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.
• Task Scheduling: Schedule tasks to run at specific times or intervals.
• Asynchronous Workflows: Run complex, multi-step tasks in the background.
• Web Browsing: Equip agents with the ability to browse the web and extract information.
• Database Integration: Query data from your database.
• Human-in-the-Loop: Support interactions that involve human input and oversight.

Get Started

1. Create your first Agent

Use the Agent starter template to kickstart your Agent development:

npm create cloudflare@latest agents-starter -- --template=cloudflare/agents-starter
npx wrangler@latest deploy

To learn more about the starter project and how to use it as a foundation for your own agents, refer to the guide on building a chat agent.

2. Install the Agents package

If you're already developing on Workers, install the agents package:

npm i agents

3. Define your Agent

Create a class that extends the Agent class:

import { Agent, AgentNamespace } 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.
}

Explore the Agent SDK reference to learn more about defining an Agent.

Why Build Agents on Cloudflare?

• Batteries (state) Included: Agents come with built-in state management.
• Communicative: Connect to agents via WebSockets for real-time updates.
• 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.
• Scalable Infrastructure: Agents run on top of Durable Objects, scaling to millions of users.
• Global Deployment: Run agents close to users or data for optimal performance.

Build on the Cloudflare Platform

Related Products

• 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.

Key Concepts

Browse the Web

Agents can browse the web using the Browser Rendering API or your preferred headless browser service.

Browser Rendering API

The Browser Rendering API allows you to spin up headless browser instances, render web pages, and interact with websites through your Agent.

Browserbase

You can also use Browserbase by using the Browserbase API directly from within your Agent.

Agents API

The Agents SDK exposes two main APIs:

• The server-side Agent class.
• The client-side AgentClient class.

Agents require Cloudflare Durable Objects.

Calling Agents

Agents are created on-the-fly and can serve multiple requests concurrently. Each Agent instance is isolated from other instances, can maintain its own state, and has a unique address.

You can create and run an instance of an Agent directly from a Worker using either:

• The routeAgentRequest helper: this will automatically map requests to an individual Agent based on the /agents/:agent/:name URL pattern.
• getAgentByName, which will create a new Agent instance if none exists by that name, or retrieve a handle to an existing instance.

Configuration

An Agent is configured like any other Cloudflare Workers project, and uses a wrangler configuration file to define where your code is and what services (bindings) it will use.

HTTP and Server-Sent Events

The Agents SDK allows you to handle HTTP requests and has native support for Server-Sent Events (SSE). This allows you build applications that can push data to clients and avoid buffering.

API Reference

Explore the detailed API reference for Agents:

• Agents API
• Browse the Web
• Calling Agents
• Configuration
• HTTP and Server-Sent Events
• Retrieval Augmented Generation
• Run Workflows
• Schedule Tasks
• Store and Sync State
• Using AI Models
• Using WebSockets

Retrieval Augmented Generation

Agents can use Retrieval Augmented Generation (RAG) to retrieve relevant information and use it augment calls to AI models.

Run Workflows

Agents can trigger asynchronous Workflows, allowing your Agent to run complex, multi-step tasks in the background.

Schedule Tasks

An Agent can schedule tasks to be run in the future by calling this.schedule(when, callback, data).

Store and Sync State

Every Agent has built-in state management capabilities, including built-in storage and synchronization between the Agent and frontend applications.

Using AI Models

Agents can communicate with AI models hosted on any provider.

Using WebSockets

Users and clients can connect to an Agent directly over WebSockets, allowing long-running, bi-directional communication with your Agent as it operates.

Guides

• Getting Started
• Remote MCP Server
• Test a Remote MCP Server

Concepts

• Authorization
• Calling LLMs
• Human in the Loop
• Model Context Protocol (MCP)
• Agents
• Workflows
• Tools

Platform

• Limits

Conclusion

The Agents SDK on Cloudflare provides a powerful platform for building and deploying AI-powered agents. With its comprehensive features, scalable infrastructure, and seamless integration with other Cloudflare services, you can create intelligent and autonomous agents that can transform the way you interact with AI.