{"id":24870924,"url":"https://github.com/cloudflare/agents","last_synced_at":"2026-04-29T00:08:20.059Z","repository":{"id":275114808,"uuid":"924394244","full_name":"cloudflare/agents","owner":"cloudflare","description":"Build and deploy AI Agents on Cloudflare ","archived":false,"fork":false,"pushed_at":"2025-04-27T02:55:41.000Z","size":2449,"stargazers_count":1544,"open_issues_count":23,"forks_count":107,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-04-28T12:15:33.325Z","etag":null,"topics":["agents","ai","cloudflare","durable-objects","workflows"],"latest_commit_sha":null,"homepage":"https://developers.cloudflare.com/agents/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-29T23:14:04.000Z","updated_at":"2025-04-28T11:30:34.000Z","dependencies_parsed_at":"2025-02-24T15:33:33.512Z","dependency_job_id":"398dfe86-2a5c-4e01-81c4-75b42d373205","html_url":"https://github.com/cloudflare/agents","commit_stats":null,"previous_names":["cloudflare/agents"],"tags_count":112,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fagents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fagents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fagents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fagents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/agents/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251311334,"owners_count":21569009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","cloudflare","durable-objects","workflows"],"created_at":"2025-02-01T04:17:33.034Z","updated_at":"2026-04-29T00:08:20.043Z","avatar_url":"https://github.com/cloudflare.png","language":"TypeScript","readme":"# Cloudflare Agents\n\n[![npm version](https://img.shields.io/npm/v/agents)](https://www.npmjs.com/package/agents)\n[![npm downloads](https://img.shields.io/npm/dw/agents)](https://www.npmjs.com/package/agents)\n\n![npm install agents](assets/npm-install-agents.svg)\n\nAgents 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.\n\nAgents 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.\n\n```sh\nnpm create cloudflare@latest -- --template cloudflare/agents-starter\n```\n\nOr add to an existing project:\n\n```sh\nnpm install agents\n```\n\n**[Read the docs](https://developers.cloudflare.com/agents/)** — getting started, API reference, guides, and more.\n\n## Quick Example\n\nA counter agent with persistent state, callable methods, and real-time sync to a React frontend:\n\n```typescript\n// server.ts\nimport { Agent, routeAgentRequest, callable } from \"agents\";\n\nexport type CounterState = { count: number };\n\nexport class CounterAgent extends Agent\u003cEnv, CounterState\u003e {\n  initialState = { count: 0 };\n\n  @callable()\n  increment() {\n    this.setState({ count: this.state.count + 1 });\n    return this.state.count;\n  }\n\n  @callable()\n  decrement() {\n    this.setState({ count: this.state.count - 1 });\n    return this.state.count;\n  }\n}\n\nexport default {\n  async fetch(request: Request, env: Env, ctx: ExecutionContext) {\n    return (\n      (await routeAgentRequest(request, env)) ??\n      new Response(\"Not found\", { status: 404 })\n    );\n  }\n};\n```\n\n```tsx\n// client.tsx\nimport { useAgent } from \"agents/react\";\nimport { useState } from \"react\";\nimport type { CounterAgent, CounterState } from \"./server\";\n\nfunction Counter() {\n  const [count, setCount] = useState(0);\n\n  const agent = useAgent\u003cCounterAgent, CounterState\u003e({\n    agent: \"CounterAgent\",\n    onStateUpdate: (state) =\u003e setCount(state.count)\n  });\n\n  return (\n    \u003cdiv\u003e\n      \u003cspan\u003e{count}\u003c/span\u003e\n      \u003cbutton onClick={() =\u003e agent.stub.increment()}\u003e+\u003c/button\u003e\n      \u003cbutton onClick={() =\u003e agent.stub.decrement()}\u003e-\u003c/button\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\nState changes sync to all connected clients automatically. Call methods like they're local functions.\n\nThe agent is a Durable Object, so it needs a binding and a SQLite migration in `wrangler.jsonc`:\n\n```jsonc\n{\n  \"name\": \"counter\",\n  \"main\": \"server.ts\",\n  \"compatibility_date\": \"2026-01-28\",\n  \"compatibility_flags\": [\"nodejs_compat\"],\n  \"durable_objects\": {\n    \"bindings\": [{ \"name\": \"CounterAgent\", \"class_name\": \"CounterAgent\" }]\n  },\n  \"migrations\": [{ \"tag\": \"v1\", \"new_sqlite_classes\": [\"CounterAgent\"] }]\n}\n```\n\n## Features\n\n| Feature                 | Description                                                                     |\n| ----------------------- | ------------------------------------------------------------------------------- |\n| **Persistent State**    | Syncs to all connected clients, survives restarts                               |\n| **Callable Methods**    | Type-safe RPC via the `@callable()` decorator                                   |\n| **Sub-agents**          | Parent/child DO composition via facets, nested routing, and typed parent lookup |\n| **Scheduling**          | One-time, recurring, and cron-based tasks                                       |\n| **WebSockets**          | Real-time bidirectional communication with lifecycle hooks                      |\n| **AI Chat**             | Message persistence, resumable streaming, server/client tool execution          |\n| **MCP**                 | Act as MCP servers or connect as MCP clients (HTTP, SSE, RPC, elicitation)      |\n| **WebMCP**              | Expose browser-side tools to agents over WebSocket                              |\n| **Workflows**           | Durable multi-step tasks with human-in-the-loop approval                        |\n| **Email**               | Send, receive, and reply via Cloudflare Email Service                           |\n| **Voice**               | Continuous STT, streaming TTS, VAD, interruption, SFU utilities                 |\n| **Browser Agents**      | Run agents in the browser tab with `agents/browser`                             |\n| **Code Mode**           | LLMs generate executable TypeScript instead of individual tool calls            |\n| **Sandboxed Execution** | Run generated code inside an isolated Worker with a virtual filesystem          |\n| **x402 Payments**       | Pay-per-call APIs and tools via the x402 protocol                               |\n| **Observability**       | Built-in tracing, metrics, and structured logs                                  |\n| **SQL**                 | Direct SQLite queries via Durable Objects                                       |\n| **React Hooks**         | `useAgent`, `useAgentChat`, `useVoiceAgent` for frontend integration            |\n| **Vanilla JS Client**   | `AgentClient` and `VoiceClient` for non-React environments                      |\n\n## Packages\n\n| Package                                                 | Description                                                                                       |\n| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |\n| [`agents`](packages/agents)                             | Core SDK — `Agent` class, routing, state, scheduling, MCP, email, workflows, x402, browser agents |\n| [`@cloudflare/ai-chat`](packages/ai-chat)               | Higher-level AI chat — persistent messages, resumable streaming, tool execution                   |\n| [`@cloudflare/think`](packages/think)                   | Opinionated chat agent base — agentic loop, stream resumption, client tools, workspace tools      |\n| [`@cloudflare/codemode`](packages/codemode)             | LLMs write executable code that calls your tools, instead of one tool call at a time              |\n| [`@cloudflare/shell`](packages/shell)                   | Sandboxed JS execution + virtual filesystem (`Workspace`) for agents                              |\n| [`@cloudflare/voice`](packages/voice)                   | Voice pipeline — STT, TTS, VAD, streaming, SFU utilities                                          |\n| [`@cloudflare/worker-bundler`](packages/worker-bundler) | Build and bundle Workers at runtime, for use with the Worker Loader binding                       |\n| [`hono-agents`](packages/hono-agents)                   | Hono middleware for adding agents to Hono apps                                                    |\n\n\u003e AI-chat modules used to live in `agents/ai-chat-agent`, `agents/chat`, `agents/ai-react`, and `agents/ai-types`. Those entry points still re-export, but they're deprecated — import from `@cloudflare/ai-chat` directly. New chat-from-scratch projects should look at `@cloudflare/think`.\n\n## Examples\n\nThe [`examples/`](examples) directory has 30+ self-contained demos. A non-exhaustive tour:\n\n- **Showcase** — [`playground/`](examples/playground) is the kitchen-sink app: state, callable methods, scheduling, chat, tools, MCP, workflows, email, voice — all in one UI\n- **Chat \u0026 assistants** — [`assistant/`](examples/assistant), [`workspace-chat/`](examples/workspace-chat), [`resumable-stream-chat/`](examples/resumable-stream-chat), [`structured-input/`](examples/structured-input), [`dynamic-tools/`](examples/dynamic-tools), [`multi-ai-chat/`](examples/multi-ai-chat)\n- **MCP** — [`mcp/`](examples/mcp), [`mcp-client/`](examples/mcp-client), [`mcp-worker/`](examples/mcp-worker), [`mcp-worker-authenticated/`](examples/mcp-worker-authenticated), [`mcp-elicitation/`](examples/mcp-elicitation), [`mcp-rpc-transport/`](examples/mcp-rpc-transport), [`webmcp/`](examples/webmcp)\n- **Code Mode \u0026 sandboxes** — [`codemode/`](examples/codemode), [`codemode-mcp/`](examples/codemode-mcp), [`codemode-mcp-openapi/`](examples/codemode-mcp-openapi), [`dynamic-workers/`](examples/dynamic-workers), [`dynamic-workers-playground/`](examples/dynamic-workers-playground), [`worker-bundler-playground/`](examples/worker-bundler-playground)\n- **Voice** — [`voice-agent/`](examples/voice-agent), [`voice-input/`](examples/voice-input), [`elevenlabs-starter/`](examples/elevenlabs-starter)\n- **Workflows \u0026 approvals** — [`workflows/`](examples/workflows), [`a2a/`](examples/a2a)\n- **Auth, payments, comms** — [`auth-agent/`](examples/auth-agent), [`cross-domain/`](examples/cross-domain), [`x402/`](examples/x402), [`x402-mcp/`](examples/x402-mcp), [`email-agent/`](examples/email-agent), [`github-webhook/`](examples/github-webhook), [`push-notifications/`](examples/push-notifications)\n- **Game \u0026 misc** — [`tictactoe/`](examples/tictactoe), [`ai-chat/`](examples/ai-chat)\n\nExamples using the [OpenAI Agents SDK](https://openai.github.io/openai-agents-js/) live in [`openai-sdk/`](openai-sdk). Work-in-progress experiments live in [`experimental/`](experimental) (no stability guarantees).\n\nRun any example locally:\n\n```sh\ncd examples/playground\nnpm start\n```\n\n## Documentation\n\n- [Full docs](https://developers.cloudflare.com/agents/) on developers.cloudflare.com\n- [`docs/`](docs) directory in this repo (synced upstream)\n- [Anthropic Patterns guide](guides/anthropic-patterns) — sequential, routing, parallel, orchestrator, evaluator\n- [Human-in-the-Loop guide](guides/human-in-the-loop) — approval workflows with pause/resume\n- [`design/`](design) — architecture and design decision records (chat API, sub-agents RFC, workspace, voice, browser tools, retries, and more)\n\n## Repository Structure\n\n| Directory                                             | Description                                              |\n| ----------------------------------------------------- | -------------------------------------------------------- |\n| [`packages/agents/`](packages/agents)                 | Core SDK                                                 |\n| [`packages/ai-chat/`](packages/ai-chat)               | AI chat layer                                            |\n| [`packages/think/`](packages/think)                   | Opinionated chat agent base                              |\n| [`packages/codemode/`](packages/codemode)             | Code Mode                                                |\n| [`packages/shell/`](packages/shell)                   | Sandboxed execution + filesystem                         |\n| [`packages/voice/`](packages/voice)                   | Voice pipeline                                           |\n| [`packages/worker-bundler/`](packages/worker-bundler) | Runtime Workers bundler                                  |\n| [`packages/hono-agents/`](packages/hono-agents)       | Hono integration                                         |\n| [`examples/`](examples)                               | Self-contained demo apps                                 |\n| [`experimental/`](experimental)                       | Work-in-progress experiments (not published)             |\n| [`openai-sdk/`](openai-sdk)                           | Examples using the OpenAI Agents SDK                     |\n| [`guides/`](guides)                                   | In-depth pattern tutorials                               |\n| [`docs/`](docs)                                       | Markdown docs synced to developers.cloudflare.com        |\n| [`site/`](site)                                       | Deployed websites (agents.cloudflare.com, AI playground) |\n| [`design/`](design)                                   | Architecture and design decision records                 |\n| [`scripts/`](scripts)                                 | Repo-wide tooling                                        |\n\n## Development\n\nNode 24+ required. npm workspaces with [Nx](https://nx.dev) for task orchestration, caching, and affected detection.\n\n```sh\nnpm install                  # install all workspaces\nnpm run build                # build all packages (Nx, cached, dependency-ordered)\nnpm run check                # sherif + export checks + oxfmt + oxlint + typecheck\nnpm run test                 # vitest + vitest-pool-workers (Workers runtime)\nnpm run test:react           # Playwright-based React hook tests\nnpx nx affected -t build     # build only what changed\nnpx nx affected -t test      # test only what changed\n```\n\nChanges to `packages/` need a changeset:\n\n```sh\nnpx changeset\n```\n\nSee [`AGENTS.md`](AGENTS.md) for deeper contributor guidance.\n\n## Contributing\n\nWe 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:\n\n- **Bug reports \u0026 feature requests** — [open an issue](https://github.com/cloudflare/agents/issues)\n- **Questions \u0026 ideas** — [start a discussion](https://github.com/cloudflare/agents/discussions)\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":["🤖 AI \u0026 Machine Learning","Repos","TypeScript","Agent Integration \u0026 Deployment Tools","AI \u0026 Machine Learning"],"sub_categories":["AI Agent Gateway","Storage Solutions"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fagents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fagents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fagents/lists"}