Cloudflare Agents SDK

Prefer the installed package and current Cloudflare Agents documentation over remembered signatures. This bundle was reconciled on 2026-09-24; examples are illustrative and were not package-typechecked or deployed.

Runtime and effect boundary

Cloudflare Agents provides Durable Object-backed identity, local SQLite state, connections, scheduling, and durable execution primitives. The application must configure principal authentication and resource authorization, make provider retries safe, and verify external outcomes separately from transcript/event persistence. Durable Object instance identity does not establish user authority.

flowchart LR
  I[Authorized input] --> A[Agent runtime]
  A --> S[(Durable state or work record)]
  A --> P[Scoped application operation]
  P --> X[External provider]
  X --> R[Readback or effect receipt]
  R --> S

Pick a primitive

Need	Start here	Required application boundary
Stateful real-time instance	state, routing, client SDK	authenticate and authorize instance access
Browser command	callable methods	validate input, idempotency, outcome status
Scheduled/queued callback	state scheduling, queues	duplicate, retry, and late-delivery behavior
Recovery from DO eviction	durable execution	complete checkpoint and recovery/compensation policy
Long-running multi-step work or approval	Workflows	bind request/action/approval and repeated progress
Chat/server turn	streaming chat, server-driven messages	transcript persistence differs from effect completion
External webhook/push	webhooks/push	verify source, dedupe, current consent, effect receipt

sequenceDiagram
  participant C as caller
  participant A as Agent
  participant D as durable record
  participant X as external system
  C->>A: authorized request and operation key
  A->>D: record accepted intent
  A->>X: attempted operation
  Note over A,X: timeout, disconnect, or eviction can leave outcome unknown
  A->>X: query by original operation identity when supported
  X-->>A: definitive outcome or unknown
  A->>D: inspect receipt or retain unknown
  alt independently confirmed
    A->>D: record completed effect
  else not confirmed
    A->>D: pending reconciliation under original identity
  end

Navigation

Core runtime

• Configuration: Wrangler bindings, exports, Vite, types, environments.
• State and scheduling: state validation, synchronization, SQL, schedules.
• Routing: public/private route boundary and Agent lookup.
• Callable methods: WebSocket RPC, streaming, commands.
• Client SDK: browser Agent access and state.

Durable/background execution

• Queues and retries: FIFO queue, retry classification, unknown result handling.
• Fibers: checkpoints, recovery, startFiber, cooperative cancellation.
• Workflows: durable steps, external waits, approval and progress.
• Observability: diagnostics, Tail Workers, correlation.

Channels and harnesses

• Streaming chat and server-driven messages: persisted chat turns and client state.
• Human approval: Workflow, Code Mode, MCP, and browser boundaries.
• Webhooks and push: verified ingress and subscription delivery.
• Think: harness-owned chat/tool loop.
• MCP, email, voice, Code Mode, and browser: integration-specific references.

Source and validation limit

The diagrams show a design boundary, not a runtime trace. Each reference names the official sources and the date it was checked; evidence scope describes the validation boundary. No installation, typecheck, Worker, Durable Object, Cloudflare service, provider, approval, notification, or browser action was run.