SkillAgentSearch skills...

agents-sdk

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

Install / Use

npx skills add cloudflare/skills --skill agents-sdk

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

90/100

Supported Platforms

Universal

Our assessment of agents-sdk

agents-sdk scores 90/100 on our quality scale, 1327th of 4,698 Development & Engineering skills we index (top 29%).

Its SKILL.md is 11 KB long, well organised into 15 sections with 5 code examples: a thorough specification that gives an agent plenty to work with.

With 2,898 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
15/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so agents-sdk is actively maintained.
  • Our last check on 2026-10-30 found the source still online.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-01. Automated pattern scan on 2026-09-30. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

agents-sdk compared with similar skills

All 4 of these similar skills score higher than agents-sdk; compare them before choosing.

SkillScoreStarsUpdatedFormat
agents-sdk (this skill)by cloudflare902.9k55d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md
lobehubby lobehub10085.6ktodayMCP Server

Frequently asked questions

How do I install agents-sdk?
Run npx skills add cloudflare/skills --skill agents-sdk. The install tabs above show the steps for each supported agent.
Which AI agents does agents-sdk work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is agents-sdk safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is agents-sdk still maintained?
The repository was last updated about 2 months ago, so agents-sdk is actively maintained.

name: agents-sdk description: Build, debug, or review Cloudflare Agents SDK applications using the agents package.

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/

| 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()
  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 for client selection and current connection examples. For chat UI and tools, also read streaming-chat.md.

References

Core

Chat & Streaming

Background Processing

Integrations

Experimental

Related Skills

View on GitHub
GitHub Stars2.9k
CategoryDevelopment
Updated1mo ago
Forks290

Languages

Shell

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions