Repolode
Submit
cloudflare

cloudflare/agents

A TypeScript SDK for building persistent, stateful AI agents on Cloudflare Durable Objects, with real-time state sync, scheduling, and MCP support.

View on GitHubWebsite
Stars
5,854
Forks
787
Open issues
171
Last commit
yesterday

What is it?

Cloudflare Agents is an SDK for running AI agents as persistent, stateful units on Cloudflare's Durable Objects. Each agent keeps its own state and storage, hibernates when idle, and wakes on demand, so one agent can be created per user, session, or game room.

The core package, `agents`, provides a base Agent class with state that syncs to connected clients in real time, callable methods exposed via a `@callable()` decorator, and built-in support for scheduling, WebSockets, SQL queries, and AI model calls. Frontend integration is available through React hooks such as `useAgent` and `useAgentChat`, as well as a vanilla JS client.

The repository is a pnpm monorepo that also includes packages for AI chat, a Code Mode approach where LLMs write executable TypeScript, a runtime Workers bundler, and Hono middleware, along with 30+ example apps.

Key features

  • 01Persistent agent state that syncs to all connected clients in real time
  • 02Type-safe callable methods via the @callable() decorator
  • 03One-time, recurring, and cron-based task scheduling
  • 04MCP server and client support
  • 05Durable multi-step workflows with human-in-the-loop approval
  • 06React hooks and a vanilla JS client for frontend integration

Use cases

  • Building a per-user AI assistant with persistent memory and chat history
  • Creating real-time multiplayer game rooms where each room is an agent
  • Exposing tools to LLMs through MCP servers hosted on Cloudflare Workers
  • Running scheduled background jobs that call AI models

Quick start

  1. 1

    Create a new project from the starter template

    npm create cloudflare@latest -- --template cloudflare/agents-starter
  2. 2

    Or add the SDK to an existing project

    npm install agents
  3. 3

    Run an example locally (from the repo, e.g. the playground)

    cd examples/playground npm start

Things to know

  • Built on Cloudflare Durable Objects, so it is designed to run on the Cloudflare platform.
  • External pull requests are not being accepted at this time.

Topics

#ai-agents#cloudflare-workers#durable-objects#typescript#mcp#llm#websockets#serverless#agents#ai

FAQ

What is agents?
A TypeScript SDK for building persistent, stateful AI agents on Cloudflare Durable Objects, with real-time state sync, scheduling, and MCP support. Cloudflare Agents is an SDK for running AI agents as persistent, stateful units on Cloudflare's Durable Objects. Each agent keeps its own state and storage, hibernates when idle, and wakes on demand, so one agent can be created per user, session, or game room.
Is agents free to use? What license does it have?
agents is open source under the MIT license. Check the license terms before using it in commercial products.
Is agents still maintained?
Actively maintained. The last commit to agents was on Oct 20, 2026.
What can I use agents for?
Building a per-user AI assistant with persistent memory and chat history Creating real-time multiplayer game rooms where each room is an agent Exposing tools to LLMs through MCP servers hosted on Cloudflare Workers Running scheduled background jobs that call AI models
How do I install agents?
Create a new project from the starter template: npm create cloudflare@latest -- --template cloudflare/agents-starter Or add the SDK to an existing project: npm install agents Run an example locally (from the repo, e.g. the playground): cd examples/playground npm start
Where can I get agents?
The source code and installation instructions are on GitHub: https://github.com/cloudflare/agents

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects