Skip to content

peteedoo/project-template / .agents/skills/imported/anomalyco--opencode/agents-sdk

agents-sdk

Verified

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.

Cloudflare Agents SDK

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

Documentation

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

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexUnverifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 465kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 318kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 318kUpdated Claude CodeCodexVerifiedInstall