Vorschlagen

Cloudflare Agents SDK

Skill

Teaches agents to build, debug and review stateful AI agents with the Cloudflare Agents SDK: state sync, scheduled tasks, RPC, MCP servers, email and streaming chat, checking the latest official docs first. Maintained by Cloudflare.

cloudflare/skills · skills/agents-sdk3.1k
Auf GitHub ansehen
README
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/index.md

TopicDocs URLUse for
Getting startedQuick startFirst agent, project setup
Adding to existing projectAdd to existing projectInstall into existing Workers app
ConfigurationConfigurationwrangler.jsonc, bindings, assets, deployment
Agent classAgents APIAgent lifecycle, patterns, pitfalls
StateStore and sync statesetState, validateStateChange, persistence
RoutingRoutingURL patterns, routeAgentRequest
Callable methodsCallable methods@callable, RPC, streaming, timeouts
SchedulingSchedule tasksschedule(), scheduleEvery(), cron
WorkflowsRun workflowsAgentWorkflow, durable multi-step tasks
HTTP/WebSocketsWebSocketsLifecycle hooks, hibernation
Chat agentsChat agentsAIChatAgent, streaming, tools, persistence
Client SDKClient SDKuseAgent, AgentClient, state, RPC, HTTP
Client toolsClient toolsClient-side tools, autoContinueAfterToolResult
Server-driven messagesAutonomous responsessaveMessages, waitUntilStable, server-initiated turns
Resumable streamingChat agentsStream recovery on disconnect
EmailEmailEmail routing, secure reply resolver
MCP clientMCP clientConnecting to MCP servers
MCP serverMCP serverBuilding MCP servers with createMcpHandler
MCP transportsMCP transportsStreamable HTTP, SSE, RPC transport options
Securing MCP serversSecuring MCPOAuth, proxy MCP, hardening
Human-in-the-loopHuman-in-the-loopWorkflow approvals, elicitation, timeout handling
Durable executionDurable executionrunFiber(), stash(), surviving DO eviction
QueueQueueBuilt-in FIFO queue, queue()
RetriesRetriesthis.retry(), backoff/jitter
ObservabilityObservabilityDiagnostics-channel events
Push notificationsPush notificationsWeb Push + VAPID from agents
WebhooksWebhooksReceiving external webhooks
Cross-domain authCross-domain authWebSocket auth, tokens, CORS
Readonly connectionsReadonlyshouldConnectionBeReadonly
VoiceVoiceExperimental STT/TTS, withVoice
Browse the webBrowser toolsExperimental CDP browser automation
ThinkThinkExperimental higher-level chat agent class
MigrationsAI SDK v5, AI SDK v6Upgrading @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}:

ClassURL
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

TaskAPI
Read statethis.state.count
Write statethis.setState({ count: 1 })
SQL querythis.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 workflowawait this.runWorkflow("ProcessingWorkflow", params)
Durable fiberawait this.runFiber("name", async (ctx) => { ... })
Enqueue workthis.queue("handler", payload)
Retry with backoffawait this.retry(fn, { maxAttempts: 5 })
Broadcast to clientsthis.broadcast(message)
Get connectionsthis.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

Ähnliche Ressourcen