Agents Sdk

Agents Sdk is a community skill for building autonomous agent applications using the Cloudflare Agents SDK, covering agent lifecycle management, state persistence, tool integration, and event-driven communication for serverless agent deployments.

What Is This?

Overview

Agents Sdk provides patterns for creating stateful, autonomous agents that run on Cloudflare Workers. It covers agent class definition with lifecycle hooks, durable state management using Cloudflare Durable Objects, tool registration and execution for agent capabilities, WebSocket-based real-time communication between agents and clients, and scheduled task execution for background processing. The skill enables developers to deploy persistent agents that maintain state across requests without managing server infrastructure.

Who Should Use This

This skill serves developers building conversational agents that need persistent state between interactions, teams deploying autonomous workflows on Cloudflare edge infrastructure, and engineers creating tool-using agents that operate within serverless environments.

Why Use It?

Problems It Solves

Traditional serverless functions lose state between invocations, requiring external databases for agent memory. WebSocket connections for real-time agent communication need dedicated server infrastructure to maintain. Tool execution in agent workflows lacks standardized patterns for registration, validation, and error handling. Scheduling recurring agent tasks requires separate infrastructure like cron services or message queues.

Core Highlights

Agent classes extend a base that provides built-in state persistence through Durable Objects. WebSocket handlers enable bidirectional real-time communication with connected clients. Tool registration defines capabilities that agents can invoke during execution with typed parameters. Scheduled execution runs agent logic at defined intervals without external cron infrastructure.

How to Use It?

Basic Usage

import { Agent } from "cloudflare-agents";

interface AgentState {
  messages: Array<{ role: string; content: string }>;
  taskCount: number;
}

export class AssistantAgent extends Agent<Env, AgentState> {
  initialState: AgentState = {
    messages: [],
    taskCount: 0,
  };

  async onMessage(
    connection: Connection,
    message: string
  ): Promise<void> {
    const parsed = JSON.parse(message);
    this.setState({
      ...this.state,
      messages: [
        ...this.state.messages,
        { role: "user", content: parsed.text },
      ],
    });
    const response = await this.processMessage(
      parsed.text
    );
    connection.send(
      JSON.stringify({ type: "response", text: response })
    );
  }

  async processMessage(text: string): Promise<string> {
    this.setState({
      ...this.state,
      taskCount: this.state.taskCount + 1,
    });
    return `Processed: ${text}`;
  }
}

Real-World Examples

import { Agent } from "cloudflare-agents";

interface ToolDefinition {
  name: string;
  description: string;
  handler: (params: Record<string, unknown>) => Promise<string>;
}

export class ToolAgent extends Agent<Env, AgentState> {
  private tools: Map<string, ToolDefinition> = new Map();

  registerTool(tool: ToolDefinition): void {
    this.tools.set(tool.name, tool);
  }

  async executeTool(
    name: string,
    params: Record<string, unknown>
  ): Promise<string> {
    const tool = this.tools.get(name);
    if (!tool) {
      throw new Error(`Tool not found: ${name}`);
    }
    return tool.handler(params);
  }

  async onMessage(
    connection: Connection,
    message: string
  ): Promise<void> {
    const { action, tool, params } = JSON.parse(message);
    if (action === "execute_tool") {
      const result = await this.executeTool(tool, params);
      connection.send(
        JSON.stringify({ type: "tool_result", result })
      );
    }
  }

  async onSchedule(): Promise<void> {
    const pending = this.state.messages.filter(
      (m) => m.role === "pending"
    );
    for (const task of pending) {
      await this.processMessage(task.content);
    }
  }
}

Advanced Tips

Use state snapshots to implement undo functionality by storing previous state versions before mutations. Implement tool execution timeouts that prevent long-running operations from blocking the agent event loop. Partition agent state into hot and cold storage, keeping frequently accessed data in memory and archiving older conversation history.

When to Use It?

Use Cases

Deploy a conversational assistant that remembers user preferences and history across sessions on Cloudflare edge. Build an automated monitoring agent that checks system health on a schedule and sends alerts through registered tools. Create a collaborative agent that coordinates with other agents through WebSocket messages for distributed task processing.

Related Topics

Cloudflare Workers, Durable Objects, serverless agent architecture, WebSocket communication patterns, and edge computing for AI applications.

Important Notes

Requirements

A Cloudflare Workers account with Durable Objects enabled. Node.js and Wrangler CLI for local development and deployment. TypeScript for type-safe agent and state definitions.

Usage Recommendations

Do: keep agent state minimal and focused on data needed between requests. Register tools with clear parameter types and descriptions for reliable execution. Use WebSocket connections for real-time interactions and HTTP endpoints for stateless queries.

Don't: store large blobs in agent state that exceed Durable Object storage limits. Create circular dependencies between agents that can cause deadlocks. Ignore connection cleanup when WebSocket clients disconnect unexpectedly.

Limitations

Durable Object state has size constraints that limit how much history an agent can retain. Cold starts add latency when an agent has not been accessed recently. Agent code updates require redeployment, and existing state must be compatible with new agent logic.