https://github.com/cloudflare/agents
Build and deploy AI Agents on Cloudflare
https://github.com/cloudflare/agents
agents ai cloudflare durable-objects workflows
Last synced: 5 days ago
JSON representation
Build and deploy AI Agents on Cloudflare
- Host: GitHub
- URL: https://github.com/cloudflare/agents
- Owner: cloudflare
- License: mit
- Created: 2025-01-29T23:14:04.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-27T02:55:41.000Z (11 months ago)
- Last Synced: 2025-04-28T12:15:33.325Z (11 months ago)
- Topics: agents, ai, cloudflare, durable-objects, workflows
- Language: TypeScript
- Homepage: https://developers.cloudflare.com/agents/
- Size: 2.34 MB
- Stars: 1,544
- Watchers: 24
- Forks: 107
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- AiTreasureBox - cloudflare/agents - 11-03_2757_0](https://img.shields.io/github/stars/cloudflare/agents.svg)|Build and deploy AI Agents on Cloudflare| (Repos)
- awesome-hacking-lists - cloudflare/agents - Build and deploy AI Agents on Cloudflare (TypeScript)
- awesome - cloudflare/agents - Build and deploy AI Agents on Cloudflare (TypeScript)
- awesome-ai-agents - cloudflare/agents - Cloudflare Agents is a framework for building and deploying intelligent, stateful AI agents that operate autonomously at the edge of the network with real-time communication and persistent memory. (Agent Integration & Deployment Tools / AI Agent Gateway)
README
# Cloudflare Agents
[](https://www.npmjs.com/package/agents)
[](https://www.npmjs.com/package/agents)
Agents are persistent, stateful execution environments for agentic workloads, powered by Cloudflare [Durable Objects](https://developers.cloudflare.com/durable-objects/). Each agent has its own state, storage, and lifecycle — with built-in support for real-time communication, scheduling, AI model calls, MCP, workflows, and more.
Agents hibernate when idle and wake on demand. You can run millions of them — one per user, per session, per game room — each costs nothing when inactive.
```sh
npm create cloudflare@latest -- --template cloudflare/agents-starter
```
Or add to an existing project:
```sh
npm install agents
```
**[Read the docs](https://developers.cloudflare.com/agents/)** — getting started, API reference, guides, and more.
## Quick Example
A counter agent with persistent state, callable methods, and real-time sync to a React frontend:
```typescript
// server.ts
import { Agent, routeAgentRequest, callable } from "agents";
export type CounterState = { count: number };
export class CounterAgent extends Agent {
initialState = { count: 0 };
@callable()
increment() {
this.setState({ count: this.state.count + 1 });
return this.state.count;
}
@callable()
decrement() {
this.setState({ count: this.state.count - 1 });
return this.state.count;
}
}
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
return (
(await routeAgentRequest(request, env)) ??
new Response("Not found", { status: 404 })
);
}
};
```
```tsx
// client.tsx
import { useAgent } from "agents/react";
import { useState } from "react";
import type { CounterAgent, CounterState } from "./server";
function Counter() {
const [count, setCount] = useState(0);
const agent = useAgent({
agent: "CounterAgent",
onStateUpdate: (state) => setCount(state.count)
});
return (
{count}
agent.stub.increment()}>+
agent.stub.decrement()}>-
);
}
```
State changes sync to all connected clients automatically. Call methods like they're local functions.
## Features
| Feature | Description |
| --------------------- | ---------------------------------------------------------------------- |
| **Persistent State** | Syncs to all connected clients, survives restarts |
| **Callable Methods** | Type-safe RPC via the `@callable()` decorator |
| **Scheduling** | One-time, recurring, and cron-based tasks |
| **WebSockets** | Real-time bidirectional communication with lifecycle hooks |
| **AI Chat** | Message persistence, resumable streaming, server/client tool execution |
| **MCP** | Act as MCP servers or connect as MCP clients |
| **Workflows** | Durable multi-step tasks with human-in-the-loop approval |
| **Email** | Receive and respond via Cloudflare Email Routing |
| **Code Mode** | LLMs generate executable TypeScript instead of individual tool calls |
| **SQL** | Direct SQLite queries via Durable Objects |
| **React Hooks** | `useAgent` and `useAgentChat` for frontend integration |
| **Vanilla JS Client** | `AgentClient` for non-React environments |
**Coming soon:** Realtime voice agents, web browsing (headless browser), sandboxed code execution, and multi-channel communication (SMS, messengers).
## Packages
| Package | Description |
| ------------------------------------------- | ------------------------------------------------------------------------------- |
| [`agents`](packages/agents) | Core SDK — Agent class, routing, state, scheduling, MCP, email, workflows |
| [`@cloudflare/ai-chat`](packages/ai-chat) | Higher-level AI chat — persistent messages, resumable streaming, tool execution |
| [`hono-agents`](packages/hono-agents) | Hono middleware for adding agents to Hono apps |
| [`@cloudflare/codemode`](packages/codemode) | Experimental — LLMs write executable code to orchestrate tools |
## Examples
The [`examples/`](examples) directory has self-contained demos covering most SDK features — MCP servers/clients, workflows, email agents, webhooks, tic-tac-toe, resumable streaming, and more. The [`playground`](examples/playground) is the kitchen-sink showcase with everything in one UI.
There are also examples using the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/) in [`openai-sdk/`](openai-sdk).
Run any example locally:
```sh
cd examples/playground
npm run dev
```
## Documentation
- [Full docs](https://developers.cloudflare.com/agents/) on developers.cloudflare.com
- [`docs/`](docs) directory in this repo (synced upstream)
- [Anthropic Patterns guide](guides/anthropic-patterns) — sequential, routing, parallel, orchestrator, evaluator
- [Human-in-the-Loop guide](guides/human-in-the-loop) — approval workflows with pause/resume
## Repository Structure
| Directory | Description |
| ----------------------------------------------- | -------------------------------------------------------- |
| [`packages/agents/`](packages/agents) | Core SDK |
| [`packages/ai-chat/`](packages/ai-chat) | AI chat layer |
| [`packages/hono-agents/`](packages/hono-agents) | Hono integration |
| [`packages/codemode/`](packages/codemode) | Code Mode (experimental) |
| [`examples/`](examples) | Self-contained demo apps |
| [`openai-sdk/`](openai-sdk) | Examples using the OpenAI Agents SDK |
| [`guides/`](guides) | In-depth pattern tutorials |
| [`docs/`](docs) | Markdown docs synced to developers.cloudflare.com |
| [`site/`](site) | Deployed websites (agents.cloudflare.com, AI playground) |
| [`design/`](design) | Architecture and design decision records |
| [`scripts/`](scripts) | Repo-wide tooling |
## Development
Node 24+ required. Uses npm workspaces.
```sh
npm install # install all workspaces
npm run build # build all packages
npm run check # full CI check (format, lint, typecheck, exports)
CI=true npm test # run tests (vitest + vitest-pool-workers)
```
Changes to `packages/` need a changeset:
```sh
npx changeset
```
See [`AGENTS.md`](AGENTS.md) for deeper contributor guidance.
## Contributing
We are not accepting external pull requests at this time — the SDK is evolving quickly and we want to keep the surface area manageable. That said, we'd love to hear from you:
- **Bug reports & feature requests** — [open an issue](https://github.com/cloudflare/agents/issues)
- **Questions & ideas** — [start a discussion](https://github.com/cloudflare/agents/discussions)
## License
[MIT](LICENSE)