Cloudflare Agents provides a framework for building stateful AI agents that run on Cloudflare’s Durable Objects platform. Unlike traditional serverless functions that are stateless and short-lived, these agents maintain state persistently at the edge, enabling continuous interactions, real-time communication, and scheduled workflows. A standout feature is “Code Mode,” where language models generate executable TypeScript code within a sandboxed environment, allowing dynamic program generation and execution on the fly.
How Cloudflare Agents manages persistent AI agents
At its core, Cloudflare Agents is a TypeScript library designed to run inside the Cloudflare Workers runtime. The framework uses Durable Objects to hold and manage agent state consistently across multiple invocations and interactions. This architecture ensures that agents can remember context, manage workflows, and maintain communication channels without losing data between requests.
The repo exposes abstractions for defining AI agents with built-in support for calling AI models, managing real-time WebSocket communication, scheduling tasks, and composing sub-agents. These features make it possible to build complex, event-driven applications that scale globally on Cloudflare’s edge network.
Communication between agents and external clients or sub-agents uses type-safe RPC calls, which improves developer experience by catching errors at compile time rather than runtime. The platform integrates multiple AI models and supports voice capabilities, highlighting its flexibility for various AI-driven scenarios.
An especially interesting architectural choice is the “Code Mode.” Here, language models generate TypeScript code snippets that run inside a sandboxed environment within the agent. This moves beyond typical AI tool calls by enabling dynamic, on-the-fly program generation and execution. It opens possibilities for agents that can adapt their behavior programmatically in response to events or inputs.
Technical strengths and tradeoffs of Cloudflare Agents
The key technical strength is the use of Durable Objects for stateful AI agents at the edge. This approach balances the scalability and low-latency benefits of serverless with the need for persistent state. Durable Objects keep the agent’s state alive across requests and across the global Cloudflare network, enabling real-time communication and scheduled workflows without relying on external databases.
The codebase is written in TypeScript, which adds type safety and improves DX, especially with the type-safe RPC system. This ensures that communication between agents and their clients or sub-agents is robust and less error-prone.
The “Code Mode” sandboxed execution is a powerful concept, but it also introduces complexity and potential security considerations. Running AI-generated code dynamically requires careful sandboxing to avoid malicious or buggy code causing issues. The repo addresses this by isolating code execution, but this is a tradeoff developers need to consider when deploying in production.
Another tradeoff is the dependency on Cloudflare’s infrastructure, particularly Durable Objects. While this gives excellent edge performance and scalability, it ties the solution to Cloudflare’s platform and may limit portability.
The repo also integrates real-time WebSocket communication, AI chat, scheduling, and voice, making it a comprehensive platform for building AI agents. However, with this breadth comes complexity — newcomers might face a learning curve understanding the interactions between these components.
Quick start with Cloudflare Agents
The repo provides clear commands for getting started with a new project or adding to an existing one. Here’s the exact quick start from the README:
npm create cloudflare@latest -- --template cloudflare/agents-starter
Or if you want to add Cloudflare Agents to an existing project:
npm install agents
This minimal setup lets you bootstrap a new Cloudflare Agents project or extend your current Cloudflare Workers application with agent capabilities.
Who should consider using Cloudflare Agents?
Cloudflare Agents is relevant for developers building AI-powered applications that require persistent state and real-time interactivity at the edge. If your use case involves stateful workflows, scheduling, or multi-agent communication, this framework offers a solid starting point.
It’s particularly suited for teams comfortable with TypeScript and Cloudflare Workers, as it tightly integrates with that environment. The “Code Mode” feature is enticing for advanced users wanting to push dynamic AI-driven behavior, but it also demands careful sandboxing and security practices.
On the downside, the solution’s dependency on Cloudflare’s infrastructure means it’s not a fit for projects needing cloud-agnostic or multi-cloud setups. Also, the complexity of the system means it’s best suited for teams with experience in distributed systems and serverless architectures.
Overall, Cloudflare Agents is a practical and well-engineered framework for building persistent AI agents on the edge, with interesting capabilities that go beyond typical serverless AI tools. The code quality is good, the architecture is thoughtfully designed, and the quick start is straightforward enough to get developers up and running.
→ GitHub Repo: cloudflare/agents ⭐ 4,824 · TypeScript