Build AI agents with Cloudflare Agents SDK on Workers + Durable Objects. Provides WebSockets, state persistence, scheduling, and multi-agent coordination. Prevents 16 documented errors. Use when: building WebSocket agents, RAG with Vectorize, MCP servers, or troubleshooting "Agent class must extend", "new_sqlite_classes", binding errors.
/plugin marketplace add jezweb/claude-skills/plugin install jezweb-tooling-skills@jezweb/claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
README.mdrules/cloudflare-agents.mdtemplates/basic-agent.tstemplates/browser-agent.tstemplates/calling-agents-worker.tstemplates/chat-agent-streaming.tstemplates/hitl-agent.tstemplates/mcp-server-basic.tstemplates/rag-agent.tstemplates/react-useagent-client.tsxtemplates/scheduled-agent.tstemplates/simple-chat-no-agents-sdk.tstemplates/state-sync-agent.tstemplates/websocket-agent.tstemplates/workflow-agent.tstemplates/wrangler-agents-config.jsoncStatus: Production Ready ✅ Last Updated: 2026-01-09 Dependencies: cloudflare-worker-base (recommended) Latest Versions: agents@0.3.3, @modelcontextprotocol/sdk@latest Production Tested: Cloudflare's own MCP servers (https://github.com/cloudflare/mcp-server-cloudflare)
Recent Updates (2025):
import { context } from agentsThe Cloudflare Agents SDK enables building AI-powered autonomous agents that run on Cloudflare Workers + Durable Objects. Agents can:
Each agent instance is a globally unique, stateful micro-server that can run for seconds, minutes, or hours.
STOP: Before using Agents SDK, ask yourself if you actually need it.
This covers 80% of chat applications. For these cases, use Vercel AI SDK directly on Workers - it's simpler, requires less infrastructure, and handles streaming automatically.
Example (no Agents SDK needed):
// worker.ts - Simple chat with AI SDK only
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
export default {
async fetch(request: Request, env: Env) {
const { messages } = await request.json();
const result = streamText({
model: openai('gpt-4o-mini'),
messages
});
return result.toTextStreamResponse(); // Automatic SSE streaming
}
}
// client.tsx - React with built-in hooks
import { useChat } from 'ai/react';
function ChatPage() {
const { messages, input, handleSubmit } = useChat({ api: '/api/chat' });
// Done. No Agents SDK needed.
}
Result: 100 lines of code instead of 500. No Durable Objects setup, no WebSocket complexity, no migrations.
This is ~20% of applications - when you need the infrastructure that Agents SDK provides.
Agents SDK IS:
Agents SDK IS NOT:
Think of it this way:
You can use them together (recommended for most cases), or use Workers AI directly (if you're willing to handle manual SSE parsing).
Building an AI application?
│
├─ Need WebSocket bidirectional communication? ───────┐
│ (Client sends while server streams, agent-initiated messages)
│
├─ Need Durable Objects stateful instances? ──────────┤
│ (Globally unique agents with persistent memory)
│
├─ Need multi-agent coordination? ────────────────────┤
│ (Agents calling/messaging other agents)
│
├─ Need scheduled tasks or cron jobs? ────────────────┤
│ (Delayed execution, recurring tasks)
│
├─ Need human-in-the-loop workflows? ─────────────────┤
│ (Approval gates, review processes)
│
└─ If ALL above are NO ─────────────────────────────→ Use AI SDK directly
(Much simpler approach)
If ANY above are YES ────────────────────────────→ Use Agents SDK + AI SDK
(More infrastructure, more power)
| Feature | AI SDK Only | Agents SDK + AI SDK |
|---|---|---|
| Setup Complexity | 🟢 Low (npm install, done) | 🔴 Higher (Durable Objects, migrations, bindings) |
| Code Volume | 🟢 ~100 lines | 🟡 ~500+ lines |
| Streaming | ✅ Automatic (SSE) | ✅ Automatic (AI SDK) or manual (Workers AI) |
| State Management | ⚠️ Manual (D1/KV) | ✅ Built-in (SQLite) |
| WebSockets | ❌ Manual setup | ✅ Built-in |
| React Hooks | ✅ useChat, useCompletion | ⚠️ Custom hooks needed |
| Multi-agent | ❌ Not supported | ✅ Built-in (routeAgentRequest) |
| Scheduling | ❌ External (Queue/Workflow) | ✅ Built-in (this.schedule) |
| Use Case | Simple chat, completions | Complex stateful workflows |
Start with AI SDK. You can always migrate to Agents SDK later if you discover you need WebSockets or Durable Objects. It's easier to add infrastructure later than to remove it.
For most developers: If you're building a chat interface and don't have specific requirements for WebSockets, multi-agent coordination, or scheduled tasks, use AI SDK directly. You'll ship faster and with less complexity.
Proceed with Agents SDK only if you've identified a specific need for its infrastructure capabilities.
npm create cloudflare@latest my-agent -- \
--template=cloudflare/agents-starter \
--ts \
--git \
--deploy false
What this creates:
cd my-existing-worker
npm install agents
Then create an Agent class:
// src/index.ts
import { Agent, AgentNamespace } from "agents";
export class MyAgent extends Agent {
async onRequest(request: Request): Promise<Response> {
return new Response("Hello from Agent!");
}
}
export default MyAgent;
Create or update wrangler.jsonc:
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "my-agent",
"main": "src/index.ts",
"compatibility_date": "2025-10-21",
"compatibility_flags": ["nodejs_compat"],
"durable_objects": {
"bindings": [
{
"name": "MyAgent", // MUST match class name
"class_name": "MyAgent" // MUST match exported class
}
]
},
"migrations": [
{
"tag": "v1",
"new_sqlite_classes": ["MyAgent"] // CRITICAL: Enables SQLite storage
}
]
}
CRITICAL Configuration Rules:
name and class_name MUST be identicalnew_sqlite_classes MUST be in first migration (cannot add later)npx wrangler@latest deploy
Your agent is now running at: https://my-agent.<subdomain>.workers.dev
Understanding what each tool does prevents confusion and helps you choose the right combination.
┌─────────────────────────────────────────────────────────┐
│ Your Application │
│ │
│ ┌────────────────┐ ┌──────────────────────┐ │
│ │ Agents SDK │ │ AI Inference │ │
│ │ (Infra Layer) │ + │ (Brain Layer) │ │
│ │ │ │ │ │
│ │ • WebSockets │ │ Choose ONE: │ │
│ │ • Durable Objs │ │ • Vercel AI SDK ✅ │ │
│ │ • State (SQL) │ │ • Workers AI ⚠️ │ │
│ │ • Scheduling │ │ • OpenAI Direct │ │
│ │ • Multi-agent │ │ • Anthropic Direct │ │
│ └────────────────┘ └──────────────────────┘ │
│ ↓ ↓ │
│ Manages connections Generates responses │
│ and state and handles streaming │
└─────────────────────────────────────────────────────────┘
↓
Cloudflare Workers + Durable Objects
Purpose: Infrastructure for stateful, real-time agents
Provides:
onStart, onConnect, onMessage, onClose)this.schedule() with cron/delays)routeAgentRequest())useAgent, AgentClient, agentFetch)Does NOT Provide:
Think of it as: The building and infrastructure (rooms, doors, plumbing) but NOT the residents (AI).
Purpose: AI inference with automatic streaming
Provides:
useChat, useCompletion, useAssistant)Example:
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
const result = streamText({
model: openai('gpt-4o-mini'),
messages: [...]
});
// Returns SSE stream - no manual parsing needed
return result.toTextStreamResponse();
When to use with Agents SDK:
Combine with Agents SDK:
import { AIChatAgent } from "agents/ai-chat-agent";
import { streamText } from "ai";
export class MyAgent extends AIChatAgent<Env> {
async onChatMessage(onFinish) {
// Agents SDK provides: WebSocket, state, this.messages
// AI SDK provides: Automatic streaming, provider abstraction
return streamText({
model: openai('gpt-4o-mini'),
messages: this.messages // Managed by Agents SDK
}).toTextStreamResponse();
}
}
Purpose: Cloudflare's on-platform AI inference
Provides:
Does NOT Provide:
Manual parsing required:
const response = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
messages: [...],
stream: true
});
// Returns raw SSE format - YOU must parse
for await (const chunk of response) {
const text = new TextDecoder().decode(chunk); // Uint8Array → string
if (text.startsWith('data: ')) { // Check SSE format
const data = JSON.parse(text.slice(6)); // Parse JSON
if (data.response) { // Extract .response field
fullResponse += data.response;
}
}
}
When to use:
Trade-off: Save money, spend time on manual parsing.
Use when: You need WebSockets/state AND want clean AI integration
import { AIChatAgent } from "agents/ai-chat-agent";
import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
export class ChatAgent extends AIChatAgent<Env> {
async onChatMessage(onFinish) {
return streamText({
model: openai('gpt-4o-mini'),
messages: this.messages, // Agents SDK manages history
onFinish
}).toTextStreamResponse();
}
}
Pros:
Cons:
Use when: You need WebSockets/state AND cost is critical
import { Agent } from "agents";
export class BudgetAgent extends Agent<Env> {
async onMessage(connection, message) {
const response = await this.env.AI.run('@cf/meta/llama-3-8b-instruct', {
messages: [...],
stream: true
});
// Manual SSE parsing required (see Workers AI section above)
for await (const chunk of response) {
// ... manual parsing ...
}
}
}
Pros:
Cons:
Use when: You DON'T need WebSockets or Durable Objects
// worker.ts - Simple Workers route
export default {
async fetch(request: Request, env: Env) {
const { messages } = await request.json();
const result = streamText({
model: openai('gpt-4o-mini'),
messages
});
return result.toTextStreamResponse();
}
}
// client.tsx - Built-in React hooks
import { useChat } from 'ai/react';
function Chat() {
const { messages, input, handleSubmit } = useChat({ api: '/api/chat' });
return <form onSubmit={handleSubmit}>...</form>;
}
Pros:
Cons:
Best for: 80% of chat applications
| Your Needs | Recommended Stack | Complexity | Cost |
|---|---|---|---|
| Simple chat, no state | AI SDK only | 🟢 Low | $$ (AI provider) |
| Chat + WebSockets + state | Agents SDK + AI SDK | 🟡 Medium | $$$ (infra + AI) |
| Chat + WebSockets + budget | Agents SDK + Workers AI | 🔴 High | $ (infra only) |
| Multi-agent workflows | Agents SDK + AI SDK | 🔴 High | $$$ (infra + AI) |
| MCP server with tools | Agents SDK (McpAgent) | 🟡 Medium | $ (infra only) |
Agents SDK is infrastructure, not AI. You combine it with AI inference tools:
The rest of this skill focuses on Agents SDK (the infrastructure layer). For AI inference patterns, see the ai-sdk-core or cloudflare-workers-ai skills.
Critical Required Configuration:
{
"durable_objects": {
"bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
},
"migrations": [
{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] } // MUST be in first migration
]
}
Common Optional Bindings: ai, vectorize, browser, workflows, d1_databases, r2_buckets
CRITICAL Migration Rules:
new_sqlite_classes MUST be in tag "v1" (cannot add SQLite to existing deployed class)name and class_name MUST match exactlySee: https://developers.cloudflare.com/agents/api-reference/configuration/
Agent Class Basics - Extend Agent<Env, State> with lifecycle methods:
onStart() - Agent initializationonRequest() - Handle HTTP requestsonConnect/onMessage/onClose() - WebSocket handlingonStateUpdate() - React to state changesKey Properties:
this.env - Environment bindings (AI, DB, etc.)this.state - Current agent state (read-only)this.setState() - Update persisted statethis.sql - Built-in SQLite databasethis.name - Agent instance identifierthis.schedule() - Schedule future tasksSee: Official Agent API docs at https://developers.cloudflare.com/agents/api-reference/agents-api/
Agents support WebSockets for bidirectional real-time communication. Use when you need:
Basic Pattern:
export class ChatAgent extends Agent<Env, State> {
async onConnect(connection: Connection, ctx: ConnectionContext) {
// Auth check, add to participants, send welcome
}
async onMessage(connection: Connection, message: WSMessage) {
// Process message, update state, broadcast response
}
}
SSE Alternative: For one-way server → client streaming (simpler, HTTP-based), use Server-Sent Events instead of WebSockets.
See: https://developers.cloudflare.com/agents/api-reference/websockets/
Two State Mechanisms:
this.setState(newState) - JSON-serializable state (up to 1GB)
this.sql - Built-in SQLite database (up to 1GB)
State Rules:
SQL Pattern:
await this.sql`CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT)`
await this.sql`INSERT INTO users (email) VALUES (${userEmail})` // ← Prepared statement
const users = await this.sql`SELECT * FROM users WHERE email = ${email}` // ← Returns array
See: https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/
Agents can schedule tasks to run in the future using this.schedule().
export class MyAgent extends Agent {
async onRequest(request: Request): Promise<Response> {
// Schedule task to run in 60 seconds
const { id } = await this.schedule(60, "checkStatus", { requestId: "123" });
return Response.json({ scheduledTaskId: id });
}
// This method will be called in 60 seconds
async checkStatus(data: { requestId: string }) {
console.log('Checking status for request:', data.requestId);
// Perform check, update state, send notification, etc.
}
}
export class MyAgent extends Agent {
async scheduleReminder(reminderDate: string) {
const date = new Date(reminderDate);
const { id } = await this.schedule(date, "sendReminder", {
message: "Time for your appointment!"
});
return id;
}
async sendReminder(data: { message: string }) {
console.log('Sending reminder:', data.message);
// Send email, push notification, etc.
}
}
export class MyAgent extends Agent {
async setupRecurringTasks() {
// Every 10 minutes
await this.schedule("*/10 * * * *", "checkUpdates", {});
// Every day at 8 AM
await this.schedule("0 8 * * *", "dailyReport", {});
// Every Monday at 9 AM
await this.schedule("0 9 * * 1", "weeklyReport", {});
// Every hour on the hour
await this.schedule("0 * * * *", "hourlyCheck", {});
}
async checkUpdates(data: any) {
console.log('Checking for updates...');
}
async dailyReport(data: any) {
console.log('Generating daily report...');
}
async weeklyReport(data: any) {
console.log('Generating weekly report...');
}
async hourlyCheck(data: any) {
console.log('Running hourly check...');
}
}
export class MyAgent extends Agent {
async manageSchedules() {
// Get all scheduled tasks
const allTasks = this.getSchedules();
console.log('Total tasks:', allTasks.length);
// Get specific task by ID
const taskId = "some-task-id";
const task = await this.getSchedule(taskId);
if (task) {
console.log('Task:', task.callback, 'at', new Date(task.time));
console.log('Payload:', task.payload);
console.log('Type:', task.type); // "scheduled" | "delayed" | "cron"
// Cancel the task
const cancelled = await this.cancelSchedule(taskId);
console.log('Cancelled:', cancelled);
}
// Get tasks in time range
const upcomingTasks = this.getSchedules({
timeRange: {
start: new Date(),
end: new Date(Date.now() + 24 * 60 * 60 * 1000) // Next 24 hours
}
});
console.log('Upcoming tasks:', upcomingTasks.length);
// Filter by type
const cronTasks = this.getSchedules({ type: "cron" });
const delayedTasks = this.getSchedules({ type: "delayed" });
}
}
Scheduling Constraints:
(task_size * count) + other_state < 1GBCRITICAL ERROR: If callback method doesn't exist:
// ❌ BAD: Method doesn't exist
await this.schedule(60, "nonExistentMethod", {});
// ✅ GOOD: Method exists
await this.schedule(60, "existingMethod", {});
async existingMethod(data: any) {
// Implementation
}
Agents can trigger asynchronous Cloudflare Workflows.
wrangler.jsonc:
{
"workflows": [
{
"name": "MY_WORKFLOW",
"class_name": "MyWorkflow"
}
]
}
If Workflow is in a different script:
{
"workflows": [
{
"name": "EMAIL_WORKFLOW",
"class_name": "EmailWorkflow",
"script_name": "email-workflows" // Different project
}
]
}
import { Agent } from "agents";
import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from "cloudflare:workers";
interface Env {
MY_WORKFLOW: Workflow;
MyAgent: AgentNamespace<MyAgent>;
}
export class MyAgent extends Agent<Env> {
async onRequest(request: Request): Promise<Response> {
const userId = new URL(request.url).searchParams.get('userId');
// Trigger a workflow immediately
const instance = await this.env.MY_WORKFLOW.create({
id: `user-${userId}`,
params: { userId, action: "process" }
});
// Or schedule a delayed workflow trigger
await this.schedule(300, "runWorkflow", { userId });
return Response.json({ workflowId: instance.id });
}
async runWorkflow(data: { userId: string }) {
const instance = await this.env.MY_WORKFLOW.create({
id: `delayed-${data.userId}`,
params: data
});
// Monitor workflow status periodically
await this.schedule("*/5 * * * *", "checkWorkflowStatus", { id: instance.id });
}
async checkWorkflowStatus(data: { id: string }) {
// Check workflow status (see Workflows docs for details)
console.log('Checking workflow:', data.id);
}
}
// Workflow definition (can be in same or different file/project)
export class MyWorkflow extends WorkflowEntrypoint<Env> {
async run(event: WorkflowEvent<{ userId: string }>, step: WorkflowStep) {
// Workflow implementation
const result = await step.do('process-data', async () => {
return { processed: true };
});
return result;
}
}
| Feature | Agents | Workflows |
|---|---|---|
| Purpose | Interactive, user-facing | Background processing |
| Duration | Seconds to hours | Minutes to hours |
| State | SQLite database | Step-based checkpoints |
| Interaction | WebSockets, HTTP | No direct interaction |
| Retry | Manual | Automatic per step |
| Use Case | Chat, real-time UI | ETL, batch processing |
Best Practice: Use Agents to coordinate multiple Workflows. Agents can trigger, monitor, and respond to Workflow results while maintaining user interaction.
Agents can use Browser Rendering for web scraping and automation:
Binding: Add "browser": { "binding": "BROWSER" } to wrangler.jsonc
Package: @cloudflare/puppeteer
Use Case: Web scraping, screenshots, automated browsing within agent workflows
See: cloudflare-browser-rendering skill for complete Puppeteer + Workers integration guide.
Agents can implement RAG using Vectorize (vector database) + Workers AI (embeddings):
Pattern: Ingest docs → generate embeddings → store in Vectorize → query → retrieve context → pass to AI
Bindings:
"ai": { "binding": "AI" } - Workers AI for embeddings"vectorize": { "bindings": [{ "binding": "VECTORIZE", "index_name": "my-vectors" }] } - Vector searchTypical Workflow:
@cf/baai/bge-base-en-v1.5)this.env.VECTORIZE.upsert(vectors))this.env.VECTORIZE.query(queryVector, { topK: 5 }))See: cloudflare-vectorize skill for complete RAG implementation guide.
Agents can call AI models using:
Architecture Note: Agents SDK provides infrastructure (WebSockets, state, scheduling). AI inference is a separate layer - use AI SDK for the "brain".
See:
ai-sdk-core skill for complete AI SDK integration patternscloudflare-workers-ai skill for Workers AI streaming parsingTwo Main Patterns:
routeAgentRequest(request, env) - Auto-route via URL pattern /agents/:agent/:name
/agents/my-agent/user-123 routes to MyAgent instance "user-123"getAgentByName<Env, T>(env.AgentBinding, instanceName) - Custom routing
const agent = getAgentByName(env.MyAgent, 'user-${userId}')Multi-Agent Communication:
export class AgentA extends Agent<Env> {
async processData(data: any) {
const agentB = getAgentByName<Env, AgentB>(this.env.AgentB, 'processor-1');
return await (await agentB).analyze(data);
}
}
CRITICAL Security: Always authenticate in Worker BEFORE creating/accessing agents. Agents should assume the caller is authorized.
See: https://developers.cloudflare.com/agents/api-reference/calling-agents/
Browser/React Integration:
AgentClient (from agents/client) - WebSocket client for browseragentFetch (from agents/client) - HTTP requests to agentsuseAgent (from agents/react) - React hook for WebSocket connections + state syncuseAgentChat (from agents/ai-react) - Pre-built chat UI hookAll client libraries automatically handle: WebSocket connections, state synchronization, reconnection logic.
See: https://developers.cloudflare.com/agents/api-reference/client-apis/
Build MCP servers using the Agents SDK.
npm install @modelcontextprotocol/sdk agents
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
export class MyMCP extends McpAgent {
server = new McpServer({ name: "Demo", version: "1.0.0" });
async init() {
// Define a tool
this.server.tool(
"add",
"Add two numbers together",
{
a: z.number().describe("First number"),
b: z.number().describe("Second number")
},
async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }]
})
);
}
}
type State = { counter: number };
export class StatefulMCP extends McpAgent<Env, State> {
server = new McpServer({ name: "Counter", version: "1.0.0" });
initialState: State = { counter: 0 };
async init() {
// Resource
this.server.resource(
"counter",
"mcp://resource/counter",
(uri) => ({
contents: [{ uri: uri.href, text: String(this.state.counter) }]
})
);
// Tool
this.server.tool(
"increment",
"Increment the counter",
{ amount: z.number() },
async ({ amount }) => {
this.setState({
...this.state,
counter: this.state.counter + amount
});
return {
content: [{
type: "text",
text: `Counter is now ${this.state.counter}`
}]
};
}
);
}
}
import { Hono } from 'hono';
const app = new Hono();
// Modern streamable HTTP transport (recommended)
app.mount('/mcp', MyMCP.serve('/mcp').fetch, { replaceRequest: false });
// Legacy SSE transport (deprecated)
app.mount('/sse', MyMCP.serveSSE('/sse').fetch, { replaceRequest: false });
export default app;
Transport Comparison:
import { OAuthProvider } from '@cloudflare/workers-oauth-provider';
export default new OAuthProvider({
apiHandlers: {
'/sse': MyMCP.serveSSE('/sse'),
'/mcp': MyMCP.serve('/mcp')
},
// OAuth configuration
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
// ... other OAuth settings
});
# Run MCP inspector
npx @modelcontextprotocol/inspector@latest
# Connect to: http://localhost:8788/mcp
Cloudflare's MCP Servers: See reference for production examples.
This skill prevents 16+ documented issues:
Error: "Cannot gradually deploy migration"
Source: https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/
Why: Migrations apply to all instances simultaneously
Prevention: Deploy migrations independently of code changes, use npx wrangler versions deploy
Error: "Cannot enable SQLite on existing class"
Source: https://developers.cloudflare.com/agents/api-reference/configuration/
Why: SQLite must be enabled in first migration
Prevention: Include new_sqlite_classes in tag "v1" migration
Error: "Binding not found" or "Cannot access undefined"
Source: https://developers.cloudflare.com/agents/api-reference/agents-api/
Why: Durable Objects require exported class
Prevention: export class MyAgent extends Agent (with export keyword)
Error: "Binding 'X' not found"
Source: https://developers.cloudflare.com/agents/api-reference/configuration/
Why: Binding name must match class name exactly
Prevention: Ensure name and class_name are identical in wrangler.jsonc
Error: Unexpected behavior with agent instances Source: https://developers.cloudflare.com/agents/api-reference/agents-api/ Why: Same name always returns same agent instance globally Prevention: Use unique identifiers (userId, sessionId) for instance names
Error: Connection state lost after disconnect Source: https://developers.cloudflare.com/agents/api-reference/websockets/ Why: WebSocket connections don't persist, but agent state does Prevention: Store important data in agent state via setState(), not connection state
Error: "Method X does not exist on Agent" Source: https://developers.cloudflare.com/agents/api-reference/schedule-tasks/ Why: this.schedule() calls method that isn't defined Prevention: Ensure callback method exists before scheduling
Error: "Maximum database size exceeded" Source: https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/ Why: Agent state + scheduled tasks exceed 1GB Prevention: Monitor state size, use external storage (D1, R2) for large data
Error: "Task payload exceeds 2MB" Source: https://developers.cloudflare.com/agents/api-reference/schedule-tasks/ Why: Each task maps to database row with 2MB limit Prevention: Keep task payloads minimal, store large data in agent state/SQL
Error: "Cannot read property 'create' of undefined" Source: https://developers.cloudflare.com/agents/api-reference/run-workflows/ Why: Workflow binding not configured in wrangler.jsonc Prevention: Add workflow binding before using this.env.WORKFLOW
Error: "BROWSER binding undefined"
Source: https://developers.cloudflare.com/agents/api-reference/browse-the-web/
Why: Browser Rendering requires explicit binding
Prevention: Add "browser": { "binding": "BROWSER" } to wrangler.jsonc
Error: "Index does not exist"
Source: https://developers.cloudflare.com/agents/api-reference/rag/
Why: Vectorize index must be created before use
Prevention: Run wrangler vectorize create before deploying agent
Error: "SSE transport deprecated"
Source: https://developers.cloudflare.com/agents/model-context-protocol/transport/
Why: SSE transport is legacy, streamable HTTP is recommended
Prevention: Use /mcp endpoint with MyMCP.serve('/mcp'), not /sse
Error: Security vulnerability Source: https://developers.cloudflare.com/agents/api-reference/calling-agents/ Why: Authentication done in Agent instead of Worker Prevention: Always authenticate in Worker before calling getAgentByName()
Error: Cross-user data leakage
Source: https://developers.cloudflare.com/agents/api-reference/calling-agents/
Why: Poor instance naming allows access to wrong agent
Prevention: Use namespaced names like user-${userId}, validate ownership
Error: "Cannot read property 'response' of undefined" or empty AI responses
Source: https://developers.cloudflare.com/workers-ai/platform/streaming/
Why: Workers AI returns streaming responses as Uint8Array in Server-Sent Events (SSE) format, not plain objects
Prevention: Use TextDecoder + SSE parsing pattern (see "Workers AI (Alternative for AI)" section above)
The problem - Attempting to access stream chunks directly fails:
const response = await env.AI.run(model, { stream: true });
for await (const chunk of response) {
console.log(chunk.response); // ❌ undefined - chunk is Uint8Array, not object
}
The solution - Parse SSE format manually:
const response = await env.AI.run(model, { stream: true });
for await (const chunk of response) {
const text = new TextDecoder().decode(chunk); // Step 1: Uint8Array → string
if (text.startsWith('data: ')) { // Step 2: Check SSE format
const jsonStr = text.slice(6).trim(); // Step 3: Extract JSON from "data: {...}"
if (jsonStr === '[DONE]') break; // Step 4: Handle termination
const data = JSON.parse(jsonStr); // Step 5: Parse JSON
if (data.response) { // Step 6: Extract .response field
fullResponse += data.response;
}
}
}
Better alternative: Use Vercel AI SDK which handles this automatically:
import { streamText } from 'ai';
import { createCloudflare } from '@ai-sdk/cloudflare';
const cloudflare = createCloudflare();
const result = streamText({
model: cloudflare('@cf/meta/llama-3-8b-instruct', { binding: env.AI }),
messages
});
// No manual parsing needed ✅
When to accept manual parsing:
When to use AI SDK instead:
agents - Agents SDK (required)@modelcontextprotocol/sdk - For building MCP servers@cloudflare/puppeteer - For web browsingai - AI SDK for model calls@ai-sdk/openai - OpenAI models@ai-sdk/anthropic - Anthropic modelswrangler-agents-config.jsonc - Complete configuration examplebasic-agent.ts - Minimal HTTP agentwebsocket-agent.ts - WebSocket handlersstate-sync-agent.ts - State management patternsscheduled-agent.ts - Task schedulingworkflow-agent.ts - Workflow integrationbrowser-agent.ts - Web browsingrag-agent.ts - RAG implementationchat-agent-streaming.ts - Streaming chatcalling-agents-worker.ts - Agent routingreact-useagent-client.tsx - React clientmcp-server-basic.ts - MCP serverhitl-agent.ts - Human-in-the-loopagent-class-api.md - Complete Agent class referenceclient-api-reference.md - Browser client APIsstate-management-guide.md - State and SQL deep divewebsockets-sse.md - WebSocket vs SSE comparisonscheduling-api.md - Task scheduling detailsworkflows-integration.md - Workflows guidebrowser-rendering.md - Web browsing patternsrag-patterns.md - RAG best practicesmcp-server-guide.md - MCP server developmentmcp-tools-reference.md - MCP tools APIhitl-patterns.md - Human-in-the-loop workflowsbest-practices.md - Production patternschat-bot-complete.md - Full chat agentmulti-agent-workflow.md - Agent orchestrationscheduled-reports.md - Recurring tasksbrowser-scraper-agent.md - Web scrapingrag-knowledge-base.md - RAG systemmcp-remote-server.md - Production MCP serverLast Verified: 2026-01-09 Package Versions: agents@0.3.3 Compliance: Cloudflare Agents SDK official documentation
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.