Cloudflare agent sandbox
Cloudflare's agent platform at the level of system architecture, data flow, and cost — the second platform we are evaluating as a managed home for our Agno workflow layer. No code, no file paths, just the picture.
At a glance
tl;drCloudflare Agents is a TypeScript SDK plus a runtime: each agent is a Durable Object backed by SQLite, alarms, and WebSockets, with optional Workflows for long-running orchestration. We supply the LLM — either Workers AI for managed inference, or BYO Claude / OpenAI through AI Gateway.
The Agents SDK is TypeScript-first. Python on Workers is open beta. Migrating our Python tool layer means either rewriting in TypeScript or running Python in Cloudflare Sandboxes (Linux containers, GA 2026) and orchestrating from a TS Agent. Core SDK + Durable Object SQLite went GA at Agents Week 2026; "Project Think" (durable execution + sub-agent facets) is in preview.
What it is
mental modelCloudflare Agents is a stateful agent SDK that runs on Workers. Each agent instance is backed by a Durable Object — isolated SQLite, alarms, WebSockets. Orchestration of multi-step durable work uses Cloudflare Workflows. Inference comes from Workers AI or any external provider through AI Gateway.
An agent is a long-lived addressable object on the edge that wakes on an event, runs briefly, persists state to its SQLite, and hibernates until the next event. Cost while hibernating is zero. The Agent class and the Durable Object underneath are inseparable: each agent instance lives or dies as a single DO.
Core primitives
vocabularyWhat each building block gives us. The eight that matter for a migration.
Base TypeScript class. Methods decorated @callable() become typed RPC endpoints.
Subclass with chat-history persistence and streaming over WebSocket.
One DO per agent. Isolated SQLite, alarms for scheduling, WebSocket hibernation, in-place state.
Durable multi-step orchestration with automatic replay and retries. The Celery replacement.
Managed inference on Cloudflare GPUs, billed per Neuron.
LLM proxy with caching, observability, rate limiting, fallback, guardrails. Works with any provider.
Vector database for RAG and semantic memory.
Object storage, eventually-consistent KV, durable message queues.
System architecture
interactiveCloudflare's WebSocket Hibernation API is what makes the cost story work: the socket stays open from the client's perspective while the DO is evicted from memory, paged in only when the next message arrives. Toggle the boundary to see which side of the wall each piece lives on.
The agent loop and any tool methods you write live inside the Durable Object. External LLM calls route through AI Gateway. Replay-safe long-running steps live in a Workflow.
Data flow
agent lifecycleA typical agent run. DO SQLite captures per-agent state throughout, and the Hibernation API keeps the socket cheap between messages.
POST /workflows/runs client → api
The frontend kicks off a run against FastAPI. Nothing edge-side has happened yet.
HTTPS → Agent.run() api → DO
FastAPI calls into the Worker, which addresses the agent's Durable Object and opens a WebSocket.
Prompt + tools to AI Gateway DO → gateway
The agent sends the prompt and tools through AI Gateway, which proxies to Claude, GPT, or Workers AI.
Tool call → execute loop
The model emits a tool call. The DO runs a local method, a Workflow step, or fetches our HTTPS endpoint.
WSS frames back DO → api
Final response streams back over WebSocket. DO SQLite captures per-agent state along the way.
Persist to Supabase api → supabase
FastAPI writes the run into Supabase and re-streams the user-visible subset (SSE / WS) to the frontend.
State and memory
three places Per-agent state lives in three places, all owned by Cloudflare. AIChatAgent persists conversation history to the agent's SQLite automatically.
Durable Object SQLite
Local to the agent, durable across restarts, deploys, and hibernation. Schema is whatever we define. The agent's working memory.
Synced KV state
A live key-value store inside the DO that auto-syncs to connected clients via the SDK's React hooks. Useful for UI mirrors of agent state.
Vectorize
External vector index for semantic memory or RAG. Long-term cross-agent memory has no first-class primitive — roll your own with a shared KV namespace or a Vectorize index.
LLM and tools
two pathsTwo paths to the model. MCP is well-supported — agents can both expose and consume MCP (HTTP, SSE, RPC, with elicitation).
Managed, in-region
Ships a catalog (Llama, Mistral, embeddings, image models) billed per Neuron. Cheap, no separate API key. Useful for utility models, less so for frontier traffic.
Proxy any provider
Proxies any external provider, including Claude. Adds caching, rate limiting, fallback, observability, DLP, Logpush. New in 2026: Unified Billing routes third-party charges to the Cloudflare invoice with a convenience fee.
Pricing
interactiveWorkers Paid plan, 2026. LLM tokens are billed by the underlying provider when you BYO; AI Gateway passes the cost through (plus the unified-billing convenience fee if enabled).
| Resource | Included | Overage |
|---|---|---|
| Baseline | $5 / month | n/a |
| Worker requests | 10M / month | $0.30 per million |
| Worker CPU time | 30M CPU-ms / month | $0.02 per million CPU-ms |
| Durable Object requests | 1M / month | $0.15 per million |
| Durable Object duration | 400,000 GB-s / month | $12.50 per million GB-s |
| DO SQLite | 5 GB-mo + 25B reads + 50M writes | $0.20/GB-mo · $0.001/M reads · $1.00/M writes |
| AI Gateway core | unlimited | free |
| AI Gateway Logpush | first 10M logs | $0.05 per million |
| Workers AI | 10,000 Neurons / day | $0.011 per 1,000 Neurons |
Same Sonar run — 80k input, 6k output on Sonnet 4.6, 60s active, 90s wall-clock. Anthropic passthrough $0.33, Worker request negligible, ~5 DO requests effectively $0, DO duration 90s × 128MB = 11.5 GB-s (well inside the 400,000 GB-s tier), AI Gateway core free. Roughly $0.33 per run — same as managed agents on tokens; the Cloudflare metering is rounding error at this scale.
Setup overview
six stepsThe high-level steps to bring up an agent sandbox for one of our existing workflows.
Provision + AI Gateway
Create a Cloudflare account, enable the Workers Paid plan, create an AI Gateway, install Wrangler locally.
Write the agent
A TypeScript class extending Agent (or AIChatAgent for chat). Tool methods are decorated callables; state lives in the agent's SQLite.
Wrap external Python tools
Either rewrite them in TypeScript (preferred for thin API wrappers), or run them in a Cloudflare Sandbox container and call from the agent over fetch.
Wire orchestration
Multi-step durable jobs become Workflows. The agent kicks off a Workflow, Cloudflare retries failed steps automatically, and the agent reads the final result.
Route LLM traffic
Through AI Gateway — choose Workers AI or an external provider (we would point Claude through AI Gateway here).
Bridge to FastAPI
The agent fronts HTTPS + WebSocket; FastAPI calls in to start a run and listens for results to write into Supabase. Local dev is Miniflare (wrangler dev); deploy is wrangler deploy.
Replacing our Agno workflow
interactiveToday: Celery → WorkflowExecutor → Agno workflow → in-process Python tools. Tomorrow: FastAPI → a Cloudflare Worker → an Agent (Durable Object) → tool methods + Workflow steps, with TS rewrites and a Python sandbox for heavy enrichment. Toggle to see what survives the move.
- FastAPI HTTP layer and routing.
- Supabase tables for workflow runs + run logs — the Worker reports back into them.
- Frontend streaming consumer — the contract does not change; we still emit SSE to the client.
- Per-tenant cost accounting in
ai_usage_log— AI Gateway exposes per-request token counts we mirror.