Home › Cloudflare Workers / Hono › Cloudflare Agents SDK rules

Cloudflare Agents SDK rules

Cursor rules for stateful AI agents on Cloudflare (agents package): Durable Object state, SQL, scheduling, and WebSockets.

CursorCloudflare Workers / Hono

How to use

Save this as .cursor/rules/cloudflare-agents.mdc in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

---
description: Cloudflare Agents SDK conventions
globs: ["src/**/*.ts","wrangler.jsonc"]
alwaysApply: false
---

# Cloudflare Agents SDK

- Agents extend `Agent<Env, State>` (or `AIChatAgent` for chat) from the `agents` package. Each agent class is a Durable Object: declare it in `wrangler.jsonc` under `durable_objects.bindings` with a `migrations` entry (`new_sqlite_classes`).
- Route requests with `routeAgentRequest(request, env)` in the Worker `fetch`; clients connect with `useAgent` / `AgentClient` from `agents/react` / `agents/client`.
- One agent instance per logical entity (user, room, ticket), addressed by name. Don't put unrelated users in one instance.
- State: `this.state` + `this.setState(...)` for small synced state (it's broadcast to clients). Larger data in the built-in SQLite via the `this.sql` tagged template, which parameterizes values.
- Scheduling with `this.schedule(when, "methodName", payload)` (delay, Date, or cron) instead of external cron for per-agent tasks.
- Expose RPC methods to clients with `@callable()`; validate their arguments.
- LLM calls through Workers AI or the provider SDK with keys in Worker secrets; stream responses back over the connection.
- Tools that act on the outside world require human confirmation in the chat flow.
- Handle `onConnect`/`onMessage`/`onClose` defensively; messages are untrusted input.
- Run `npx wrangler types` after binding changes.

## Done when
`npx tsc --noEmit` passes, tests run with `@cloudflare/vitest-pool-workers`, and `npx wrangler deploy --dry-run` succeeds.