agents-sdk

Build, debug, or review Cloudflare Agents SDK applications using the agents package.

109,899
installs: 0 up / 0 down, score 0.00
votes: 3,198
repo stars
Updated: 1 month ago
In the catalog since: 18 Sept 2026
From: cloudflare/skills

Get it through your agent npx skills add cloudflare/skills@agents-sdk

Skill instructions

Rendered from the published SKILL.md, 198 lines.

Cloudflare Agents SDK

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

Retrieval Sources

Cloudflare docs: https://developers.cloudflare.com/agents/index.md

Topic	Docs URL	Use for
Getting started	Quick start	First agent, project setup
Adding to existing project	Add to existing project	Install into existing Workers app
Configuration	Configuration	`wrangler.jsonc`, bindings, assets, deployment
Agent class	Agents API	Agent lifecycle, patterns, pitfalls
State	Store and sync state	`setState`, `validateStateChange`, persistence
Routing	Routing	URL patterns, `routeAgentRequest`
Callable methods	Callable methods	`@callable`, RPC, streaming, timeouts
Scheduling	Schedule tasks	`schedule()`, `scheduleEvery()`, cron
Workflows	Run workflows	`AgentWorkflow`, durable multi-step tasks
HTTP/WebSockets	WebSockets	Lifecycle hooks, hibernation
Chat agents	Chat agents	`AIChatAgent`, streaming, tools, persistence
Client SDK	Client SDK	`useAgent`, `AgentClient`, state, RPC, HTTP
Client tools	Client tools	Client-side tools, `autoContinueAfterToolResult`
Server-driven messages	Autonomous responses	`saveMessages`, `waitUntilStable`, server-initiated turns
Resumable streaming	Chat agents	Stream recovery on disconnect
Email	Email	Email routing, secure reply resolver
MCP client	MCP client	Connecting to MCP servers
MCP server	MCP server	Building MCP servers with `createMcpHandler`
MCP transports	MCP transports	Streamable HTTP, SSE, RPC transport options
Securing MCP servers	Securing MCP	OAuth, proxy MCP, hardening
Human-in-the-loop	Human-in-the-loop	Workflow approvals, elicitation, timeout handling
Durable execution	Durable execution	`runFiber()`, `stash()`, surviving DO eviction
Queue	Queue	Built-in FIFO queue, `queue()`
Retries	Retries	`this.retry()`, backoff/jitter
Observability	Observability	Diagnostics-channel events
Push notifications	Push notifications	Web Push + VAPID from agents
Webhooks	Webhooks	Receiving external webhooks
Cross-domain auth	Cross-domain auth	WebSocket auth, tokens, CORS
Readonly connections	Readonly	`shouldConnectionBeReadonly`
Voice	Voice	Experimental STT/TTS, `withVoice`
Browse the web	Browser tools	Experimental CDP browser automation
Think	Think	Experimental higher-level chat agent class
Migrations	AI SDK v5, AI SDK v6	Upgrading `@cloudflare/ai-chat`

Capabilities

The Agents SDK provides:

Persistent state — SQLite-backed, auto-synced to clients via setState
Callable RPC — @callable() methods invoked over WebSocket
Scheduling — One-time, recurring (scheduleEvery), and cron tasks
Workflows — Durable multi-step background processing via AgentWorkflow
Durable execution — runFiber() / stash() for work that survives DO eviction
Queue — Built-in FIFO queue with retries via queue()
Retries — this.retry() with exponential backoff and jitter
MCP integration — Connect to MCP servers or build your own with createMcpHandler
Email handling — Receive and reply to emails with secure routing
Streaming chat — AIChatAgent with resumable streams, message persistence, tools
Server-driven messages — saveMessages, waitUntilStable for proactive agent turns
React hooks — useAgent, useAgentChat for client apps
Observability — diagnostics_channel events for state, RPC, schedule, lifecycle
Push notifications — Web Push + VAPID delivery from agents
Webhooks — Receive and verify external webhooks
Voice (experimental) — STT/TTS via @cloudflare/voice
Browser tools (experimental) — CDP-powered browsing via agents/browser
Think (experimental) — Higher-level chat agent via @cloudflare/think

FIRST: Verify Installation

npm ls agents  # Should show agents package

If not installed:

npm install agents

For chat agents:

npm install agents @cloudflare/ai-chat ai @ai-sdk/react

Wrangler Configuration

{
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
  },
  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
}

Gotchas:

Do NOT enable experimentalDecorators in tsconfig (breaks @callable)
Never edit old migrations — always add new tags
Each agent class needs its own DO binding + migration entry
Add "ai": { "binding": "AI" } for Workers AI

Agent Class

import { Agent, routeAgentRequest, callable } from "agents";

type State = { count: number };

export class Counter extends Agent<Env, State> {
  initialState = { count: 0 };

  validateStateChange(nextState: State, source: Connection | "server") {
    if (nextState.count < 0) throw new Error("Count cannot be negative");
  }

  onStateUpdate(state: State, source: Connection | "server") {
    console.log("State updated:", state);
  }

  @callable()

Show the whole skill (78 more lines)

increment() { this.setState({ count: this.state.count + 1 }); return this.state.count; } }

export default { fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 }) };


## Routing

Requests route to `/agents/{agent-name}/{instance-name}`:

| Class | URL |
|-------|-----|
| `Counter` | `/agents/counter/user-123` |
| `ChatRoom` | `/agents/chat-room/lobby` |

Client: `useAgent({ agent: "Counter", name: "user-123" })`

Custom routing: use `getAgentByName(env.MyAgent, "instance-id")` then `agent.fetch(request)`.

## Core APIs

| Task | API |
|------|-----|
| Read state | `this.state.count` |
| Write state | `this.setState({ count: 1 })` |
| SQL query | `` this.sql`SELECT * FROM users WHERE id = ${id}` `` |
| Schedule (delay) | `await this.schedule(60, "task", payload)` |
| Schedule (cron) | `await this.schedule("0 * * * *", "task", payload)` |
| Schedule (interval) | `await this.scheduleEvery(30, "poll")` |
| RPC method | `@callable() myMethod() { ... }` |
| Streaming RPC | `@callable({ streaming: true }) stream(res) { ... }` |
| Start workflow | `await this.runWorkflow("ProcessingWorkflow", params)` |
| Durable fiber | `await this.runFiber("name", async (ctx) => { ... })` |
| Enqueue work | `this.queue("handler", payload)` |
| Retry with backoff | `await this.retry(fn, { maxAttempts: 5 })` |
| Broadcast to clients | `this.broadcast(message)` |
| Get connections | `this.getConnections(tag?)` |

## React Client

Read [client-sdk.md](references/client-sdk.md) for client selection and current connection examples. For chat UI and tools, also read [streaming-chat.md](references/streaming-chat.md).

## References

### Core
- **[references/state-scheduling.md](references/state-scheduling.md)** — State persistence, scheduling, SQL
- **[references/callable.md](references/callable.md)** — RPC methods, streaming, timeouts
- **[references/routing.md](references/routing.md)** — URL patterns, custom routing, `getAgentByName`
- **[references/configuration.md](references/configuration.md)** — Wrangler config, bindings, Vite setup

### Chat & Streaming
- **[references/streaming-chat.md](references/streaming-chat.md)** — AIChatAgent, resumable streams, tools
- **[references/client-sdk.md](references/client-sdk.md)** — `useAgent`, `useAgentChat`, `AgentClient`
- **[references/server-driven-messages.md](references/server-driven-messages.md)** — Trigger patterns, `saveMessages`
- **[references/human-in-the-loop.md](references/human-in-the-loop.md)** — Approval flows, `needsApproval`

### Background Processing
- **[references/workflows.md](references/workflows.md)** — Durable Workflows integration
- **[references/durable-execution.md](references/durable-execution.md)** — `runFiber`, `stash`, surviving eviction
- **[references/queue-retries.md](references/queue-retries.md)** — Built-in queue, retry with backoff

### Integrations
- **[references/mcp.md](references/mcp.md)** — MCP client and server, transports, securing
- **[references/email.md](references/email.md)** — Email routing and handling
- **[references/webhooks-push.md](references/webhooks-push.md)** — Webhooks, push notifications
- **[references/observability.md](references/observability.md)** — Diagnostics-channel events

### Experimental
- **[references/think.md](references/think.md)** — `@cloudflare/think` higher-level chat agent
- **[references/voice.md](references/voice.md)** — `@cloudflare/voice` STT/TTS
- **[references/codemode.md](references/codemode.md)** — Code Mode for tool orchestration
- **[references/browse-the-web.md](references/browse-the-web.md)** — CDP browser tools

Get it through your agent

Call the Graph-of-Skills MCP server's retrieve_skill_bundle tool and it returns this skill's text inside your budget.

{
  "tool": "retrieve_skill_bundle",
  "arguments": {
    "query": "agents-sdk"
  }
}

New to this? Set up Graph-of-Skills or get a free key. The text on this page comes from its authors: how skills are sourced and what we check. If none fits your task, your agent can write a skill for your own library. To keep a skill from your own library on a machine, see how to install one of your skills.

Share on X Share on LinkedIn Share on Bluesky Share on Hacker News

Share on Reddit

Source

Source repository cloudflare/skills
Listing on skills.sh

From cloudflare/skills via skills.sh

Related skills

google-agents-cli-workflow
This skill should be used when the user wants to "develop an agent", "build an agent using ADK", "run the agent locally", "debug agent code", "test an agent", "deploy an agent", "publish an agent", "monitor an agent", or needs the ADK (Agent Development Kit) development lifecycle and coding guidelines. Entrypoint for building ADK agents. Always active — provides the full workflow (scaffold, build, evaluate, deploy, publish, observe), code preservation rules, model selection guidance, and troubleshooting steps for ADK or any agent development.
524,224 installs
google-agents-cli-deploy
This skill should be used when the user wants to "deploy an agent", "deploy my ADK agent", "set up CI/CD", "configure secrets", "troubleshoot a deployment", or needs guidance on Agent Runtime, Cloud Run, or GKE deployment targets, or binding an agent to an Agent Gateway. Covers deployment workflows, service accounts, rollback, and production infrastructure. Applies to any framework agents-cli deploys (ADK, LangChain, ...). Part of the agents-cli skills suite. Do NOT use for agent API code patterns (ADK: use google-agents-cli-adk-code), evaluation (use google-agents-cli-eval), or project scaffolding (use google-agents-cli-scaffold).
524,996 installs
cloudflare
Discover and choose Cloudflare products for apps, APIs, AI agents, storage, networking, and security. Use for architecture and product selection, including when the user describes a need without naming a Cloudflare product; then find the relevant skill or documentation.
142,037 installs
ai-sdk
Answer questions about the AI SDK and help build AI-powered features. Use when developers: (1) Ask about AI SDK functions like generateText, streamText, ToolLoopAgent, embed, or tools, (2) Want to build AI agents, chatbots, RAG systems, or text generation features, (3) Have questions about AI providers (OpenAI, Anthropic, Google, etc.), streaming, tool calling, structured output, or embeddings, (4) Use React hooks like useChat or useCompletion. Triggers on: "AI SDK", "Vercel AI SDK", "generateText", "streamText", "add AI to my app", "build an agent", "tool calling", "structured output", "useChat".
66,876 installs
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
492,548 installs

More from cloudflare/skills

cloudflare
Discover and choose Cloudflare products for apps, APIs, AI agents, storage, networking, and security. Use for architecture and product selection, including when the user describes a need without naming a Cloudflare product; then find the relevant skill or documentation.
142,037 installs
wrangler
Run or troubleshoot Wrangler CLI commands in projects that have a wrangler.jsonc, wrangler.json, or wrangler.toml file, including local development, Previews, deployment, and resource management. For new projects and projects without a Wrangler configuration file, use the cf CLI instead.
133,407 installs
workers-best-practices
Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.
130,193 installs
durable-objects
Build, debug, or review Cloudflare Durable Objects code for persistent state and coordination.
114,014 installs
web-perf
Audit, diagnose, or optimize website loading and interaction performance, Core Web Vitals, and Lighthouse performance scores.
113,827 installs

Content is provided as published by its creators; you are responsible for how you use it.

To request removal, use the contact form.