| name | cf-agents |
| description | Build, deploy, and manage AI Agents on Cloudflare using the Agents SDK (package "agents"). Use this skill whenever the user wants to create an AI agent, chat agent, MCP server/client, stateful WebSocket app, or any agentic application on Cloudflare Workers. Trigger on mentions of "Cloudflare agent", "agents SDK", "AIChatAgent", "McpAgent", "Durable Object agent", "remote MCP server", "human-in-the-loop agent", agentic workflows on CF, or deploying agents to Workers. Also trigger when user asks about building stateful AI applications with scheduling, tool calling, state sync, or real-time communication on Cloudflare — even if they don't say "agent" explicitly. If they mention building a chat app with tool use on Workers, or an MCP server on Cloudflare, use this skill. |
Building and Deploying AI Agents on Cloudflare
TypeScript framework for stateful, real-time AI agents on Cloudflare Workers + Durable Objects.
Before you start
Read the reference file(s) for what you're building:
| Building... | Read |
|---|
| Any agent (start here) | references/core-api.md |
| Chat agent with AI + tools | references/chat-agents.md |
| MCP server or client | references/mcp.md |
| Agent patterns (chaining, routing, parallelization, etc.) | references/patterns.md |
Always read references/core-api.md first — it covers the foundational Agent class, configuration, state, SQL, scheduling, and deployment.
Key Concepts
- Package:
agents (npm), v0.5.x. Requires nodejs_compat compatibility flag.
- AI SDK: Vercel AI SDK (
ai v6), with workers-ai-provider v3 and ai-gateway-provider v3 for Cloudflare models.
- Client packages:
agents/client (vanilla JS), agents/react (useAgent), agents/ai-react (useAgentChat).
- Each Agent instance is a Durable Object — stateful micro-server with SQLite, WebSockets, and scheduling. Hibernates when idle.
Quick Start
npx create-cloudflare@latest -- --template cloudflare/agents-starter
npm i agents
Gotchas & Tips
- Always export your Agent class from the entry point. Both
export class and export default handler are required.
- Class name -> kebab-case for routing.
MyAgent becomes my-agent in URL paths.
- One alarm per DO. The SDK multiplexes multiple schedules onto a single Durable Object alarm internally.
- State is JSON-serializable only. No functions, no circular refs.
this.sql is synchronous. Uses tagged template literals with automatic parameterization.- Secrets go in
.dev.vars locally, wrangler secret put for production.
- Use
cors: true in routeAgentRequest options if your frontend is on a different origin.
- Agents SDK v0.3+ uses AI SDK v6. Use
@ai-sdk/react@^3.0.0, ai@^6.0.0.
this.retry() is available for retrying async operations with exponential backoff.this.destroy() wipes all state, tables, alarms, and evicts the DO. Safe to call from scheduled tasks.
