Cloudflare Agents
Build persistent, real-time, stateful AI agents on Cloudflare.
The sources show isolated execution, human-approval workflows, persistent state, external email/payment/MCP capabilities, and credentials supplied through workflow secrets; the MIT file and package author field also provide attribution. They do not systematically document least-privilege policy, data destinations, secret lifecycle, per-effect confirmation, or recoverable rollback. The Bonk workflow grants broad permissions including contents: write and uses a floating @main action, while no audit, vulnerability-response, or comprehensive supply-chain policy is shown. Most trust controls are therefore only thinly evidenced. Publisher identity remains unknown as instructed and is not used to infer safety.
The README, package scripts, compatibility matrix, and limited tests give reasonably consistent static evidence for build procedures, AI SDK 6/7 compatibility, timeout forwarding, and ordered recovery states. Node, pnpm, and major dependency requirements are explicit. Deductions reflect the absence of executed results, availability guarantees, and broad failure-message examples; the supplied tests cannot establish repository-wide failure handling.
The material addresses chat, MCP, workflows, voice, browser, payment, and multiple client scenarios. It identifies experimental code as unstable, marks legacy imports deprecated, and supplies detailed Workers, Durable Objects, and local-development configuration. Environment fit is therefore thorough. However, exact triggering conditions, routing authorization boundaries, and guidance on when individual powerful capabilities should activate are not developed beyond basic examples.
The README has strong information architecture, package and directory maps, installation commands, configuration examples, categorized demos, and development commands. The separate LICENSE fully establishes MIT terms. Deductions cover stability risk from rapid evolution and deprecated entry points, the lack of a consolidated FAQ and comprehensive operational limitations, and the absence of an actual changelog despite changeset tooling and an npm badge. Maintenance channels are named, but external pull requests are closed and publisher registry verification is absent.
The quick example is readily usable as server, client, and Wrangler configuration, while the extensive examples and support for persistence, synchronization, scheduling, and integrations indicate substantial practical value. Many broad capabilities are asserted in the README rather than evidenced individually by the supplied code. Cost-benefit evidence is especially thin: the claim that idle agents cost nothing is not accompanied by analysis of request, storage, model, voice, or third-party service costs.
The central positioning can be compared across the README, package manifest, workflow, and tests; compatibility ranges, commands, licensing, and limited recovery behavior trace to concrete files. Deductions reflect that many feature, scale, and cost claims appear only as README summaries, the supplied implementation evidence is narrow, and no independent source is included. The material distinguishes experimental, deprecated, and preferred paths, but does not attach evidence or assumptions to every promotional claim.
- This is a static review without executing code or tests; it does not establish runtime safety, correctness, determinism, or deployment availability.
- Before deployment, review the Bonk workflow's write permissions, floating third-party @main action, and secret exposure; pin action revisions and narrow permissions where possible.
- Email, payments, MCP, generated code, and sandbox features can create external effects or process sensitive data; applications need explicit authorization, confirmation, auditing, retention, and recovery policies.
- The claim that idle agents cost nothing does not imply zero total cost; Durable Objects, storage, AI models, voice, and third-party services require separate cost assessment.
What does this agent do, and when should you use it?
Cloudflare Agents is a TypeScript SDK for building and deploying agents backed by Durable Objects, with independent state, storage, and lifecycle. Its core `Agent` class exposes persistent state, type-safe RPC, scheduling, WebSockets, SQLite, MCP, workflows, email, and observability interfaces. The repository also supplies layered packages such as `@cloudflare/ai-chat`, `@cloudflare/think`, `@cloudflare/codemode`, `@cloudflare/shell`, and `@cloudflare/voice`, plus React and vanilla JavaScript clients. Instances hibernate while idle, wake on demand, and can synchronize state changes across connected clients. It is a strong fit for teams already using, or prepared to adopt, Cloudflare Workers and Durable Objects; the core execution and deployment model is tied to that platform.
On the server, an application subclasses Agent<Env, State>, declares initial state and lifecycle behavior, and marks type-safe client-callable methods with @callable(). routeAgentRequest() routes incoming Worker requests to the appropriate agent instance. The Durable Object persists the agent's state and can broadcast updates to connected React or vanilla JavaScript clients. Applications connect through useAgent, useAgentChat, useVoiceAgent, AgentClient, or VoiceClient, and may schedule one-off, recurring, or cron tasks. Optional packages add persistent chat and resumable streams, server and client tool execution, MCP server and client support, approval-based durable workflows, voice processing, email, x402 payments, and browser-tab agents. Code Mode lets models produce executable TypeScript that calls tools, while @cloudflare/shell runs generated JavaScript in an isolated Worker with a virtual filesystem.
- A SaaS team that needs isolated, durable state for each user or session can map every agent to a Durable Object that hibernates when unused.
- A frontend team building a multiplayer room, game room, or collaborative interface can use WebSocket lifecycle hooks and automatic state synchronization.
- A TypeScript team developing a chat assistant can use
@cloudflare/ai-chatfor stored messages, resumable streaming, and coordinated server or client tools. - A business system that runs long-lived tasks with approval gates can implement durable, pausable, human-in-the-loop processes through Workflows.
- A developer integrating an MCP tool environment can expose an agent as an MCP server or connect it to MCP services over HTTP, SSE, or RPC with elicitation.
- A team creating a voice or telephone assistant can use
@cloudflare/voicefor STT, TTS, VAD, streaming, and interruption handling.
What are this agent's strengths and limitations?
- Each agent receives isolated state, storage, and lifecycle management, with persistence across restarts and automatic synchronization to connected clients.
- One SDK family covers RPC, scheduling, WebSockets, chat, MCP, workflows, email, voice, payments, SQL, and observability, reducing the amount of infrastructure teams must assemble.
- Idle instances hibernate and wake on demand, making the model suitable for large numbers of per-user, per-session, or per-room agents.
- Both React hooks and vanilla JavaScript clients are provided, with shared TypeScript types supporting type-safe remote method calls.
- The repository includes more than 30 self-contained examples, architecture records, and pattern guides covering concrete integration scenarios.
- Core state and lifecycle behavior depend on Cloudflare Durable Objects, so moving to another runtime would require those platform services to be reimplemented.
- Every Durable Object agent needs a binding and SQLite migration, adding deployment configuration and migration-management overhead.
- Source development requires Node.js 24+ and uses pnpm with Nx, which may conflict with teams standardized on other Node versions or package managers.
- Earlier AI chat import paths are deprecated; existing applications must migrate to
@cloudflare/ai-chat, while new projects must also evaluate@cloudflare/think. - The repository is not currently accepting external pull requests, limiting outside contributors to issues and discussions.
- Features under
experimental/carry no stability guarantee and should not be treated as dependable production APIs.
How do you install or deploy this agent?
For a new project, run npm create cloudflare@latest -- --template cloudflare/agents-starter. To add the SDK to an existing project, run npm install agents. Repository development requires Node.js 24+ and uses pnpm workspaces; the documented source workflow is pnpm install, pnpm run build, pnpm run check, and pnpm run test. The supplied material does not specify the required Cloudflare credentials, login command, or final deployment command, so those deployment steps cannot be stated from this source.
How do you use this agent?
Define a class such as CounterAgent extends Agent<Env, CounterState>, set initialState = { count: 0 }, and decorate remotely callable methods such as increment() and decrement() with @callable(). Invoke routeAgentRequest(request, env) from the Worker's fetch handler. In wrangler.jsonc, add a Durable Object binding whose name and class_name identify CounterAgent, then register it under new_sqlite_classes in a migration; the example also sets compatibility_date to 2026-06-11 and enables nodejs_compat. A React client connects with useAgent({ agent: "CounterAgent", onStateUpdate }) and calls a method through agent.stub.increment(). To run the repository's playground example locally, execute cd examples/playground followed by npm start.
How does this agent compare with similar options?
The repository offers several internal abstraction levels. agents is the core SDK; @cloudflare/ai-chat concentrates on persistent messages, resumable streams, and tool execution; and @cloudflare/think is an opinionated chat-agent base recommended for new chat-from-scratch projects. Frontends can choose React hooks or the non-React AgentClient and VoiceClient. The older agents/ai-chat-agent, agents/chat, agents/ai-react, and agents/ai-types entry points still re-export functionality but are deprecated.
FAQ
Can it be deployed without Cloudflare?
Is MCP required to run an agent?
Do idle agents keep consuming execution resources?
Can a non-React frontend use the SDK?
useAgent, useAgentChat, and useVoiceAgent, the repository provides AgentClient and VoiceClient for non-React environments.What is the risk of adopting experimental features?
experimental/ directory is explicitly reserved for work-in-progress experiments with no stability guarantees. Production systems should favor published packages and assess upgrade risk separately.