Agents SDK от Cloudflare

Помогает строить приложения на Agents SDK от Cloudflare: агенты с состоянием на Durable Objects, RPC, расписания, очереди, Workflows, чат на AIChatAgent, MCP и почта. Для случаев, когда нужен ИИ-агент или чат на Workers.

Модели и APIПак: Скиллы Cloudflare206 строкagents-sdk
Автор
Источник
cloudflare/skills/skills/agents-sdk @ 5108325
Лицензия
Apache-2.0

Об этом скилле

Что делает

Скилл помогает агенту писать, отлаживать и ревьюить приложения на Agents SDK от Cloudflare — npm-пакете agents, где каждый класс агента является Durable Object со своим хранилищем SQLite. Начинается он с проверки npm ls agents (чат-приложениям нужны ещё @cloudflare/ai-chat, ai и @ai-sdk/react) и с конфигурации, без которой класс агента не заработает: биндинг Durable Object, миграция new_sqlite_classes и nodejs_compat. Среди ловушек: experimentalDecorators в tsconfig ломает @callable, а старые миграции не правят никогда.

В SKILL.md — минимальный агент с setState, validateStateChange и методом @callable(), маршрутизация на /agents/{kebab-класс}/{экземпляр} через routeAgentRequest и основные API: this.sql, schedule() с задержкой или cron, scheduleEvery(), runWorkflow(), runFiber(), queue(), retry(), broadcast(). Остальное закрывает таблица из 33 тем со ссылками на документацию.

Темы разнесены по девятнадцати справочникам. Часть — короткие руководства с кодом: потоковые callable-методы, параметры маршрутизации, конфигурация с плагином Vite, файберы runFiber() (stash заменяет контрольную точку целиком, при исключении повтора нет), почта с ответами, подписанными HMAC, вебхуки и Web Push с ключами VAPID, события diagnostics_channel. Другие отсылают к документации с парой проверок: состояние или SQL, встроенная очередь (dead-letter очереди нет), Workflows, подтверждения человеком, MCP (createMcpHandler вместо устаревшего McpAgent). Четыре посвящены экспериментальным возможностям: @cloudflare/think (нужен флаг совместимости experimental), @cloudflare/voice, Code Mode и браузерные инструменты на CDP — двум последним нужен биндинг worker_loaders. skill-feedback.md готовит issue в cloudflare/skills, который вы сначала одобряете.

Когда включать и когда не надо

Для ИИ-агентов с состоянием, чатов со стримингом и инструментами, агентной работы по расписанию или долгих задач, а также MCP-серверов и клиентов на Workers.

Для обычного Durable Object без функций агента лучше подойдёт скилл про Durable Objects. Многие справочники — в основном ссылки, так что агенту нужен доступ в сеть.

Как поставить и вызвать

Команда установки ниже скачивает SKILL.md, справочники и лицензию. Вызвать вручную:

  • Claude Code: /agents-sdk или попросить скилл по имени.
  • Codex: $agents-sdk.
  • Cursor: наберите / в чате Agent и выберите agents-sdk.

Пример: /agents-sdk Сделай чат-агента поддержки на AIChatAgent, который назначает обратный звонок по расписанию и спрашивает подтверждение перед возвратом денег.

Чем отличается от похожих

Durable Objects в Cloudflare — слой ниже, для объектов, которые вы пишете сами. Создание MCP-сервера строит обычный MCP-сервер для внешнего API и добавляет прогон оценки; здесь MCP — одна из возможностей агента на Workers. Приложения для ChatGPT на Apps SDK тоже строятся вокруг MCP-сервера, но для приложения с виджетом внутри ChatGPT.

Установка

Выполните одну команду — она сохранит SKILL.md и файлы, которые он использует, в папку скиллов агента. Claude Code и Codex подхватывают новый скилл без перезапуска; если скилл не появился, перезапустите агента.

Скилл написан на английском — агент поймёт его и ответит вам по-русски.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/agents-sdk/SKILL.md https://anymodel.org/en/skills/cloudflare/agents-sdk/SKILL.md -o ~/.claude/skills/agents-sdk/LICENSE https://anymodel.org/en/skills/cloudflare/agents-sdk/LICENSE -o ~/.claude/skills/agents-sdk/references/browse-the-web.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/browse-the-web.md -o ~/.claude/skills/agents-sdk/references/callable.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/callable.md -o ~/.claude/skills/agents-sdk/references/client-sdk.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/client-sdk.md -o ~/.claude/skills/agents-sdk/references/codemode.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/codemode.md -o ~/.claude/skills/agents-sdk/references/configuration.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/configuration.md -o ~/.claude/skills/agents-sdk/references/durable-execution.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/durable-execution.md -o ~/.claude/skills/agents-sdk/references/email.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/email.md -o ~/.claude/skills/agents-sdk/references/human-in-the-loop.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/human-in-the-loop.md -o ~/.claude/skills/agents-sdk/references/mcp.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/mcp.md -o ~/.claude/skills/agents-sdk/references/observability.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/observability.md -o ~/.claude/skills/agents-sdk/references/queue-retries.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/queue-retries.md -o ~/.claude/skills/agents-sdk/references/routing.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/routing.md -o ~/.claude/skills/agents-sdk/references/server-driven-messages.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/server-driven-messages.md -o ~/.claude/skills/agents-sdk/references/skill-feedback.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/skill-feedback.md -o ~/.claude/skills/agents-sdk/references/state-scheduling.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/state-scheduling.md -o ~/.claude/skills/agents-sdk/references/streaming-chat.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/streaming-chat.md -o ~/.claude/skills/agents-sdk/references/think.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/think.md -o ~/.claude/skills/agents-sdk/references/voice.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/voice.md -o ~/.claude/skills/agents-sdk/references/webhooks-push.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/webhooks-push.md -o ~/.claude/skills/agents-sdk/references/workflows.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/workflows.md
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/agents-sdk/SKILL.md https://anymodel.org/en/skills/cloudflare/agents-sdk/SKILL.md -o ~/.agents/skills/agents-sdk/LICENSE https://anymodel.org/en/skills/cloudflare/agents-sdk/LICENSE -o ~/.agents/skills/agents-sdk/references/browse-the-web.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/browse-the-web.md -o ~/.agents/skills/agents-sdk/references/callable.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/callable.md -o ~/.agents/skills/agents-sdk/references/client-sdk.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/client-sdk.md -o ~/.agents/skills/agents-sdk/references/codemode.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/codemode.md -o ~/.agents/skills/agents-sdk/references/configuration.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/configuration.md -o ~/.agents/skills/agents-sdk/references/durable-execution.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/durable-execution.md -o ~/.agents/skills/agents-sdk/references/email.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/email.md -o ~/.agents/skills/agents-sdk/references/human-in-the-loop.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/human-in-the-loop.md -o ~/.agents/skills/agents-sdk/references/mcp.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/mcp.md -o ~/.agents/skills/agents-sdk/references/observability.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/observability.md -o ~/.agents/skills/agents-sdk/references/queue-retries.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/queue-retries.md -o ~/.agents/skills/agents-sdk/references/routing.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/routing.md -o ~/.agents/skills/agents-sdk/references/server-driven-messages.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/server-driven-messages.md -o ~/.agents/skills/agents-sdk/references/skill-feedback.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/skill-feedback.md -o ~/.agents/skills/agents-sdk/references/state-scheduling.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/state-scheduling.md -o ~/.agents/skills/agents-sdk/references/streaming-chat.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/streaming-chat.md -o ~/.agents/skills/agents-sdk/references/think.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/think.md -o ~/.agents/skills/agents-sdk/references/voice.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/voice.md -o ~/.agents/skills/agents-sdk/references/webhooks-push.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/webhooks-push.md -o ~/.agents/skills/agents-sdk/references/workflows.md https://anymodel.org/en/skills/cloudflare/agents-sdk/references/workflows.md
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/browse-the-web.md','references/callable.md','references/client-sdk.md','references/codemode.md','references/configuration.md','references/durable-execution.md','references/email.md','references/human-in-the-loop.md','references/mcp.md','references/observability.md','references/queue-retries.md','references/routing.md','references/server-driven-messages.md','references/skill-feedback.md','references/state-scheduling.md','references/streaming-chat.md','references/think.md','references/voice.md','references/webhooks-push.md','references/workflows.md') { $p = Join-Path "$HOME\.claude\skills\agents-sdk" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/cloudflare/agents-sdk/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE','references/browse-the-web.md','references/callable.md','references/client-sdk.md','references/codemode.md','references/configuration.md','references/durable-execution.md','references/email.md','references/human-in-the-loop.md','references/mcp.md','references/observability.md','references/queue-retries.md','references/routing.md','references/server-driven-messages.md','references/skill-feedback.md','references/state-scheduling.md','references/streaming-chat.md','references/think.md','references/voice.md','references/webhooks-push.md','references/workflows.md') { $p = Join-Path "$HOME\.agents\skills\agents-sdk" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/cloudflare/agents-sdk/$f" -UseBasicParsing -OutFile $p }

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/cloudflare/agents-sdk/SKILL.md

SKILL.md

Исходник

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()
  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

Skill feedback

If the user reports that this skill gave incorrect or outdated guidance, or is missing information, read references/skill-feedback.md.

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Скиллы Cloudflare

Лучшие практики Cloudflare Workers

Проверяет код и конфигурацию Cloudflare Workers по правилам для прода: даты совместимости, логи и трейсы, стриминг, waitUntil, биндинги вместо REST, Web Crypto, типы Env. Для случаев, когда Worker пишут, ревьюят или готовят к выкладке.

Wrangler CLI для Cloudflare

Ведёт команды и конфигурацию Wrangler в проектах с wrangler.jsonc или wrangler.toml: сверяется со справкой и документацией, бережёт секреты, окружения и Previews. Для случаев, когда Worker деплоят, настраивают или чинят через Wrangler.

Durable Objects в Cloudflare

Помогает писать и ревьюить Durable Objects в Cloudflare: объект на сущность, хранилище SQLite и миграции, RPC-методы, alarms, WebSocket и тесты на Vitest. Для случаев, когда приложению на Workers нужны общее состояние и координация.

Веб-фреймворки на Cloudflare Workers

Настраивает приложения на Astro, SvelteKit, React Router, TanStack Start, Nuxt, Hono и SPA под Cloudflare Workers, выбирая C3, Wrangler или cf по состоянию проекта. Для случаев, когда приложение создают, переносят или деплоят на Workers.

Локальная разработка Workers

Запускает и отлаживает Workers локально через cf dev, wrangler dev или плагин Vite, а в Local Explorer читает и наполняет данные биндингов и смотрит трейсы. Для случаев, когда локальный запрос падает или непонятно, что вернул биндинг.

CLI cf для API Cloudflare

Находит и выполняет команды CLI cf от Cloudflare (бета) через cf cli search, cf schema и пробные прогоны, выбирает между cf и Wrangler. Для случаев, когда нужно работать с DNS, зонами, D1, KV или R2 из терминала или начать проект на Workers.

Аудит скорости сайта

Проводит аудит скорости страницы через Chrome DevTools MCP: трейс, Core Web Vitals по порогам, сеть, снимок доступности и настройки сборки, с исправлениями по приоритету. Для случаев, когда страница тормозит или оценка Lighthouse низкая.