AutoGineer
Generated banner for Agents SDK
Generated logo for Agents SDK

Agents SDK

OpenAIOfficialCreated by CloudflareDistributed by OpenAI

  • Skill
  • Tool integration
  • Cloud and DevOps
  • Apache-2.0
  • No issues found
Download ZIP

From the author

Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, or chat applications. Covers Agent class, state management, callable RPC, Workflows integration, and React hooks. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
— the description by Cloudflare

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Agents SDK provides a framework for building stateful, durable AI agents directly on Cloudflare Workers. It simplifies the development of complex agentic applications by offering built-in state management, RPC capabilities via WebSockets, durable workflows, and seamless integration with MCP servers. The SDK is designed to handle real-time interactions, scheduled tasks, and email routing, while providing React hooks for easy client-side integration.

What it does

  • Enables creation of stateful agents with SQLite-backed persistence.
  • Exposes agent methods as callable RPC endpoints via WebSockets.
  • Supports durable, multi-step background workflows.
  • Integrates with MCP servers for expanded tool capabilities.
  • Provides React hooks for real-time agent communication.
  • Handles scheduled tasks and cron jobs within the agent lifecycle.

When to use it

  • When building stateful AI agents on the Cloudflare Workers platform.
  • When you need durable, multi-step workflows for background processing.
  • When implementing real-time WebSocket-based communication between clients and agents.
  • When connecting to or building MCP servers for agent tool use.
  • When you require persistent state that auto-syncs to client applications.

Advantages

  • Native integration with Cloudflare Workers and Durable Objects.
  • Simplifies complex state management and persistence.
  • Reduces round-trips with callable RPC methods.
  • Provides robust support for resumable streaming and durable workflows.
  • Streamlines client-side development with dedicated React hooks.

Usage examples

“How do I define a callable method in my Cloudflare Agent?”
You use the @callable() decorator on your class method, which allows it to be invoked remotely via WebSocket RPC from a client.
“How can I persist state in my agent?”
You use the this.setState() method within your Agent class, which updates the SQLite-backed state and triggers any defined validation or update hooks.
“How do I connect a React frontend to my agent?”
You use the useAgent hook from the agents/react package, providing the agent name and instance identifier to manage state and communication.
“Can I run background tasks in my agent?”
Yes, you can use the this.schedule() or this.scheduleEvery() methods to trigger one-time or recurring tasks, or use AgentWorkflow for durable multi-step processes.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/openai/agents-sdk/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip agents-sdk.zip -d .agents/skills

Documentation by Cloudflare

Cloudflare Agents SDK

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

Retrieval Sources

Fetch current docs from https://github.com/cloudflare/agents/tree/main/docs before implementing.

TopicDocUse for
Getting starteddocs/getting-started.mdFirst agent, project setup
Statedocs/state.mdsetState, validateStateChange, persistence
Routingdocs/routing.mdURL patterns, routeAgentRequest, basePath
Callable methodsdocs/callable-methods.md@callable, RPC, streaming, timeouts
Schedulingdocs/scheduling.mdschedule(), scheduleEvery(), cron
Workflowsdocs/workflows.mdAgentWorkflow, durable multi-step tasks
HTTP/WebSocketsdocs/http-websockets.mdLifecycle hooks, hibernation
Emaildocs/email.mdEmail routing, secure reply resolver
MCP clientdocs/mcp-client.mdConnecting to MCP servers
MCP serverdocs/mcp-servers.mdBuilding MCP servers with McpAgent
Client SDKdocs/client-sdk.mduseAgent, useAgentChat, React hooks
Human-in-the-loopdocs/human-in-the-loop.mdApproval flows, pausing workflows
Resumable streamingdocs/resumable-streaming.mdStream recovery on disconnect

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

Capabilities

The Agents SDK provides:

  • Persistent state - SQLite-backed, auto-synced to clients

  • Callable RPC - @callable() methods invoked over WebSocket

  • Scheduling - One-time, recurring (scheduleEvery), and cron tasks

  • Workflows - Durable multi-step background processing via AgentWorkflow

  • MCP integration - Connect to MCP servers or build your own with McpAgent

  • Email handling - Receive and reply to emails with secure routing

  • Streaming chat - AIChatAgent with resumable streams

  • React hooks - useAgent, useAgentChat for client apps

FIRST: Verify Installation

npm ls agents  # Should show agents package

If not installed:

npm install agents

Wrangler Configuration

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

Agent Class

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

type State = { count: number };

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

  // Validation hook - runs before state persists (sync, throwing rejects the update)
  validateStateChange(nextState: State, source: Connection | "server") {
    if (nextState.count < 0) throw new Error("Count cannot be negative");
  }

  // Notification hook - runs after state persists (async, non-blocking)
  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" })

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)

React Client

import { useAgent } from "agents/react";

function App() {
  const [state, setLocalState] = useState({ count: 0 });

  const agent = useAgent({
    agent: "Counter",
    name: "my-instance",
    onStateUpdate: (newState) => setLocalState(newState),
    onIdentity: (name, agentType) => console.log(`Connected to ${name}`)
  });

  return (
    <button onClick={() => agent.setState({ count: state.count + 1 })}>
      Count: {state.count}
    </button>
  );
}

References

Files

Requirements and compatibility

Written for: OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Cloudflare
Publisher
OpenAI (Official)
Distributed by
OpenAI
Source
openai/plugins · plugins/cloudflare/skills/agents-sdk · commit d420d13
Licence
Apache License 2.0 (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Cloudflare or OpenAI.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download agents-sdk.zip