secondsky__claude-skills/plugins/cloudflare-agents

Cloudflare Agents SDK Skill

Status: Production Ready ✅ Last Updated: 2025-10-21 Production Tested: Cloudflare's own MCP servers (https://github.com/cloudflare/mcp-server-cloudflare)

---

Auto-Trigger Keywords

Primary Keywords (Core Technology):

• cloudflare agents
• agents sdk
• cloudflare agents sdk
• agents package
• npm create cloudflare agents
• npm i agents
• build agents cloudflare
• ai agents workers
• durable objects agents
• stateful agents

Secondary Keywords (API Surfaces):

• Agent class, extend agent, onRequest agent, onConnect agent, onMessage agent
• useAgent hook, AgentClient, agentFetch, useAgentChat
• this.setState agent, agent state management, state sync agents, this.sql agent
• this.schedule, schedule tasks agent, cron agents, agent alarms
• run workflows agent, agent workflows, workflow integration agents
• browse web agents, puppeteer agents, browser rendering agents
• rag agents, vectorize agents, agent embeddings, retrieval augmented generation agents
• mcp server, McpAgent, mcp tools, model context protocol
• routeAgentRequest, getAgentByName, agent instance, calling agents
• AIChatAgent, chat agents, streaming chat agent
• websocket agents, server-sent events agents, sse agents

Use Case Keywords:

• stateful micro-servers
• long-running agents
• autonomous agents
• human in the loop agents, hitl agents, approval workflow agents
• multi-agent systems, agent orchestration, agent communication
• persistent agent state
• agent with database
• scheduled agent tasks
• agent web scraping

Error-Based Keywords (Common Issues):

• "Agent class must extend"
• "new_sqlite_classes"
• "migrations required"
• "binding not found"
• "agent not exported"
• "callback does not exist"
• "state limit exceeded"
• "migration tag"
• "workflow binding missing"
• "browser binding required"
• "vectorize index not found"
• "Cannot enable SQLite on existing class"
• "Migrations are atomic"

---

What This Skill Does

This skill provides comprehensive knowledge for the Cloudflare Agents SDK - a framework for building AI-powered autonomous agents on Cloudflare Workers + Durable Objects.

Agents can:

• ✅ Communicate in real-time via WebSockets and Server-Sent Events
• ✅ Persist state with built-in SQLite database (up to 1GB per agent)
• ✅ Schedule tasks using delays, specific dates, or cron expressions
• ✅ Run asynchronous Cloudflare Workflows
• ✅ Browse the web using Browser Rendering API + Puppeteer
• ✅ Implement RAG with Vectorize + Workers AI embeddings
• ✅ Build MCP (Model Context Protocol) servers
• ✅ Support human-in-the-loop patterns
• ✅ Scale to millions of independent agent instances globally

Each agent instance is a globally unique, stateful micro-server that can run for seconds, minutes, or hours.

---

Known Issues Prevented

This skill prevents 15+ documented issues:

Issue	Source	Impact
Migrations not atomic	Durable Objects Migrations	Cannot gradually deploy migrations - deployment fails
Missing new_sqlite_classes	Agents Configuration	Cannot enable SQLite later - must be in v1 migration
Agent class not exported	Agents API	Binding fails with "Cannot access undefined"
Binding name mismatch	Configuration	"Binding not found" error
Global uniqueness not understood	Agents API	Same name = same instance globally (can cause data leakage)
WebSocket state not persisted	WebSockets	Connection state lost after disconnect
Scheduled task callback missing	Schedule Tasks	Runtime error: "Method does not exist"
State size limit exceeded	State Management	Database exceeds 1GB limit
Task payload too large	Schedule Tasks	Task exceeds 2MB limit
Workflow binding missing	Run Workflows	Cannot access workflow binding
Browser binding required	Browse the Web	Puppeteer fails without binding
Vectorize index not found	RAG	Query fails on non-existent index
MCP transport confusion	MCP Transport	Using deprecated SSE instead of /mcp
Authentication bypass	Calling Agents	Security vulnerability
Instance naming errors	Calling Agents	Cross-user data leakage

---

When to Use This Skill

Use this skill when:

• ✅ Building AI-powered agents that need to persist state
• ✅ Creating chat applications with streaming responses
• ✅ Implementing real-time WebSocket communication
• ✅ Scheduling recurring tasks or delayed execution
• ✅ Running asynchronous workflows
• ✅ Building RAG systems with Vectorize + Workers AI
• ✅ Creating MCP servers for LLM tool use
• ✅ Implementing human-in-the-loop approval workflows
• ✅ Web scraping with headless browsers
• ✅ Building multi-agent systems
• ✅ Needing stateful micro-servers that scale globally
• ✅ Encountering Agent configuration or deployment errors

---

When NOT to Use This Skill

Don't use this skill when:

• ❌ Building simple stateless Workers (use cloudflare-worker-base instead)
• ❌ Only need key-value storage (use cloudflare-kv instead)
• ❌ Only need SQL database (use cloudflare-d1 instead)
• ❌ Building static websites (use cloudflare-worker-base with Static Assets)
• ❌ Project doesn't require persistent state or WebSockets

---

Quick Example

// Create an Agent class
import { Agent } from "agents";

interface Env {
  AI: Ai;
}

export class MyAgent extends Agent<Env> {
  async onRequest(request: Request): Promise<Response> {
    return Response.json({ agent: this.name, state: this.state });
  }

  async onConnect(connection: Connection, ctx: ConnectionContext) {
    connection.send("Welcome!");
  }

  async onMessage(connection: Connection, message: WSMessage) {
    if (typeof message === 'string') {
      connection.send(`Echo: ${message}`);
    }
  }
}

export default MyAgent;

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

---

What's Included

SKILL.md (1300+ lines)

Complete guide covering all 17 API surfaces:

• Agent Class API
• HTTP & Server-Sent Events
• WebSockets
• State Management (setState, SQL)
• Schedule Tasks (delays, dates, cron)
• Run Workflows
• Browse the Web (Browser Rendering)
• RAG (Vectorize + Workers AI)
• Using AI Models
• Calling Agents (routeAgentRequest, getAgentByName)
• Client APIs (AgentClient, useAgent, agentFetch)
• Model Context Protocol (MCP servers)
• Patterns (Chat Agents, HITL, Tools, Multi-Agent)
• Configuration & Migrations
• Critical Rules & Known Issues

13 Templates (templates/)

Production-ready code examples:

1. wrangler-agents-config.jsonc - Complete configuration
2. basic-agent.ts - HTTP agent basics
3. websocket-agent.ts - Real-time communication
4. state-sync-agent.ts - State management + SQL
5. scheduled-agent.ts - Task scheduling
6. workflow-agent.ts - Workflow integration
7. browser-agent.ts - Web scraping
8. rag-agent.ts - RAG with Vectorize
9. chat-agent-streaming.ts - Streaming chat
10. calling-agents-worker.ts - Agent routing
11. react-useagent-client.tsx - React client
12. mcp-server-basic.ts - MCP server
13. hitl-agent.ts - Human-in-the-loop

---

Dependencies

Recommended:

• cloudflare-worker-base - Foundation (Hono, Vite, Workers setup)

Optional (by feature):

• cloudflare-workers-ai - For Workers AI model calls
• cloudflare-vectorize - For RAG with Vectorize
• cloudflare-d1 - For additional persistent storage
• cloudflare-r2 - For file storage

NPM Packages:

• agents - Agents SDK (required)
• @modelcontextprotocol/sdk - For MCP servers
• @cloudflare/puppeteer - For web browsing
• ai - AI SDK for model calls
• @ai-sdk/openai - OpenAI models
• @ai-sdk/anthropic - Anthropic models

---

Official Documentation

• Agents SDK: https://developers.cloudflare.com/agents/
• API Reference: https://developers.cloudflare.com/agents/api-reference/
• GitHub (Examples): https://github.com/cloudflare/agents
• MCP Servers: https://github.com/cloudflare/mcp-server-cloudflare
• Model Context Protocol: https://modelcontextprotocol.io/

---

Related Skills

• cloudflare-worker-base - Foundation for Workers projects
• cloudflare-workers-ai - Workers AI models
• cloudflare-vectorize - Vector database for RAG
• cloudflare-d1 - D1 serverless SQL
• cloudflare-r2 - R2 object storage

---

Maintained by: Claude Skills Maintainers License: MIT Last Verified: 2025-10-21