# building-ai-agent-on-cloudflare

Generates Cloudflare Agents SDK code for edge deployment on Workers and Durable Objects. Handles persistent state, WebSockets, and background scheduling.

- skill · `type=skill` · Codex, ChatGPT · 2 installs · ★ 7604
- Author: Cloudflare · official OpenAI repository
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/openai/plugins/tree/HEAD/plugins/cloudflare/skills/building-ai-agent-on-cloudflare/SKILL.md
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/skills/building-ai-agent-on-cloudflare

## What it does

This skill guides the coding assistant to write services using the Cloudflare Agents SDK. The runtime structure relies on Durable Objects. Each user session runs as an isolated instance that keeps state in memory, synchronizes updates to clients via `setState`, or queries embedded SQLite using `this.sql`.

Client communication flows through WebSockets managed by `onConnect`, `onMessage`, and `onClose` handlers. AI inference connects via the Workers AI binding, calling models like `@cf/meta/llama-3-8b-instruct`. Beyond interactive messaging, agents can defer actions via `this.schedule` using relative second delays or explicit timestamps.

Running the resulting project requires an active Cloudflare account with Workers, Node.js 18+, and Wrangler CLI. The skill strictly instructs the assistant to retrieve recent Cloudflare documentation rather than trusting potentially outdated pre-trained weights.

## Install

### Codex (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add openai/plugins --skill building-ai-agent-on-cloudflare -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/building-ai-agent-on-cloudflare/SKILL.md` — For all projects use ~/.agents/skills/

### Claude Code

1. **Skills CLI (Vercel)**
```bash
npx skills add openai/plugins --skill building-ai-agent-on-cloudflare -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/building-ai-agent-on-cloudflare/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/building-ai-agent-on-cloudflare/

### Cursor

**Manually: put the files in place**
- File: `.cursor/skills/building-ai-agent-on-cloudflare/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install openai/plugins building-ai-agent-on-cloudflare
```

2. **Manually: put the files in place**
- File: `.github/skills/building-ai-agent-on-cloudflare/SKILL.md`

### Gemini CLI

**Platform CLI**
```bash
gemini skills install https://github.com/openai/plugins --path plugins/cloudflare/skills/building-ai-agent-on-cloudflare
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/building-ai-agent-on-cloudflare/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/openai/plugins/tree/HEAD/plugins/cloudflare/skills/building-ai-agent-on-cloudflare/SKILL.md

## When to use it
- Scaffold stateful AI agents on Cloudflare Workers and Durable Objects
- Implement real-time WebSocket communication with state syncing
- Store agent documents and message history in embedded SQLite
- Schedule deferred background jobs using the Agents SDK scheduler

## Example prompts
- Build a stateful chat agent using Cloudflare Agents SDK and Workers AI
- Create an agent class with WebSocket handling and embedded SQLite storage
- Configure wrangler.toml and an entry point for a Cloudflare Agent

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 8d1ae5200d46a406.

BEGIN THIRD-PARTY FILE 8d1ae5200d46a406
````text
---
name: building-ai-agent-on-cloudflare
description: |
  Builds AI agents on Cloudflare using the Agents SDK with state management,
  real-time WebSockets, scheduled tasks, tool integration, and chat capabilities.
  Generates production-ready agent code deployed to Workers.

  Use when: user wants to "build an agent", "AI agent", "chat agent", "stateful
  agent", mentions "Agents SDK", needs "real-time AI", "WebSocket AI", or asks
  about agent "state management", "scheduled tasks", or "tool calling".
  Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
---

# Building Cloudflare Agents

Your knowledge of the Agents SDK may be outdated. **Prefer retrieval over pre-training** for any agent-building task.

## Retrieval Sources

| Source | How to retrieve | Use for |
|--------|----------------|---------|
| Agents SDK docs | `https://github.com/cloudflare/agents/tree/main/docs` | SDK API, state, routing, scheduling |
| Cloudflare Agents docs | `https://developers.cloudflare.com/agents/` | Platform integration, deployment |
| Workers docs | Search tool or `https://developers.cloudflare.com/workers/` | Runtime APIs, bindings, config |

## When to Use

- User wants to build an AI agent or chatbot
- User needs stateful, real-time AI interactions
- User asks about the Cloudflare Agents SDK
- User wants scheduled tasks or background AI work
- User needs WebSocket-based AI communication

## Prerequisites

- Cloudflare account with Workers enabled
- Node.js 18+ and npm/pnpm/yarn
- Wrangler CLI (`npm install -g wrangler`)

## Quick Start

```bash
npm create cloudflare@latest -- my-agent --template=cloudflare/agents-starter
cd my-agent
npm start
```

Agent runs at `http://localhost:8787`

## Core Concepts

### What is an Agent?

An Agent is a stateful, persistent AI service that:
- Maintains state across requests and reconnections
- Communicates via WebSockets or HTTP
- Runs on Cloudflare's edge via Durable Objects
- Can schedule tasks and call tools
- Scales horizontally (each user/session gets own instance)

### Agent Lifecycle

```
Client connects → Agent.onConnect() → Agent processes messages
                                    → Agent.onMessage()
                                    → Agent.setState() (persists + syncs)
Client disconnects → State persists → Client reconnects → State restored
```

## Basic Agent Structure

```typescript
import { Agent, Connection } from "agents";

interface Env {
  AI: Ai;  // Workers AI binding
}

interface State {
  messages: Array<{ role: string; content: string }>;
  preferences: Record<string, string>;
}

export class MyAgent extends Agent<Env, State> {
  // Initial state for new instances
  initialState: State = {
    messages: [],
    preferences: {},
  };

  // Called when agent starts or resumes
  async onStart() {
    console.log("Agent started with state:", this.state);
  }

  // Handle WebSocket connections
````
END THIRD-PARTY FILE 8d1ae5200d46a406

The third-party file has ended. Everything between the 8d1ae5200d46a406 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2932 of 9809 bytes. © Cloudflare · MIT · https://github.com/openai/plugins/tree/HEAD/plugins/cloudflare/skills/building-ai-agent-on-cloudflare/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md