## 1. Project Overview & Quickstart (cloudflare/AGENTS) ## File: README.md # 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. The agent is a Durable Object, so it needs a binding and a SQLite migration in `wrangler.jsonc`: ```jsonc { "name": "counter", "main": "server.ts", "compatibility_date": "2026-06-11", "compatibility_flags": ["nodejs_compat"], "durable_objects": { "bindings": [{ "name": "CounterAgent", "class_name": "CounterAgent" }] }, "migrations": [{ "tag": "v1", "new_sqlite_classes": ["CounterAgent"] }] } ``` ## Features | Feature | Description | | ----------------------- | ------------------------------------------------------------------------------- | | **Persistent State** | Syncs to all connected clients, survives restarts | | **Callable Methods** | Type-safe RPC via the `@callable()` decorator | | **Sub-agents** | Parent/child DO composition via facets, nested routing, and typed parent lookup | | **Agent Tools** | Run chat-capable sub-agents as tools with streaming child timelines | | **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 (HTTP, SSE, RPC, elicitation) | | **WebMCP** | Expose page-local tools or bridge remote MCP tools to browser agents | | **Workflows** | Durable multi-step tasks with human-in-the-loop approval | | **Email** | Send, receive, and reply via Cloudflare Email Service | | **Voice** | Continuous STT, streaming TTS, VAD, interruption, SFU utilities | | **Browser Agents** | Run agents in the browser tab with `agents/browser` | | **Code Mode** | LLMs generate executable TypeScript instead of individual tool calls | | **Sandboxed Execution** | Run generated code inside an isolated Worker with a virtual filesystem | | **x402 Payments** | Pay-per-call APIs and tools via the x402 protocol | | **Observability** | Built-in tracing, metrics, and structured logs | | **SQL** | Direct SQLite queries via Durable Objects | | **React Hooks** | `useAgent`, `useAgentChat`, `useVoiceAgent` for frontend integration | | **Vanilla JS Client** | `AgentClient` and `VoiceClient` for non-React environments | ## Packages | Package | Description | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | [`agents`](packages/agents) | Core SDK — `Agent` class, routing, state, scheduling, MCP, email, workflows, x402, browser agents | | [`@cloudflare/ai-chat`](packages/ai-chat) | Higher-level AI chat — persistent messages, resumable streaming, tool execution | | [`@cloudflare/think`](packages/think) | Opinionated chat agent base — agentic loop, stream resumption, client tools, workspace tools | | [`@cloudflare/codemode`](packages/codemode) | LLMs write executable code that calls your tools, instead of one tool call at a time | | [`@cloudflare/shell`](packages/shell) | Sandboxed JS execution + virtual filesystem (`Workspace`) for agents | | [`@cloudflare/voice`](packages/voice) | Voice pipeline — STT, TTS, VAD, streaming, SFU utilities | | [`@cloudflare/worker-bundler`](packages/worker-bundler) | Build and bundle Workers at runtime, for use with the Worker Loader binding | | [`hono-agents`](packages/hono-agents) | Hono middleware for adding agents to Hono apps | > 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`. ## Examples The [`examples/`](examples) directory has 30+ self-contained demos. A non-exhaustive tour: - **Showcase** — [`playground/`](examples/playground) is the kitchen-sink app: state, callable methods, scheduling, chat, tools, MCP, workflows, email, voice — all in one UI - **Chat & assistants** — [`assistant/`](examples/assistant), [`agents-as-tools/`](examples/agents-as-tools), [`agent-skills/`](examples/agent-skills), [`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), [`context-overflow-recovery/`](examples/context-overflow-recovery) - **MCP** — [`mcp/`](examples/mcp), [`mcp-client/`](examples/mcp-client), [`mcp-server/`](examples/mcp-server), [`mcp-worker/`](examples/mcp-worker), [`mcp-worker-authenticated/`](examples/mcp-worker-authenticated), [`mcp-elicitation-mrtr/`](examples/mcp-elicitation-mrtr), [`mcp-elicitation/`](examples/mcp-elicitation), [`mcp-rpc-transport/`](examples/mcp-rpc-transport), [`webmcp/`](examples/webmcp), [`webmcp-react/`](examples/webmcp-react) - **Code Mode & 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) - **Voice** — [`voice-agent/`](examples/voice-agent) is the unified voice pipeline example with Workers AI, AssemblyAI, Telnyx, and ElevenLabs STT; [`voice-input/`](examples/voice-input) covers dictation; [`telnyx-voice-agent/`](examples/telnyx-voice-agent) covers phone transport; [`elevenlabs-starter/`](examples/elevenlabs-starter) covers broader ElevenLabs media APIs - **Workflows & approvals** — [`workflows/`](examples/workflows), [`a2a/`](examples/a2a) - **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) - **Game & misc** — [`tictactoe/`](examples/tictactoe), [`ai-chat/`](examples/ai-chat) Examples 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). Run any example locally: ```sh cd examples/playground npm start ``` ## 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 - [`design/`](design) — architecture and design decision records (chat API, sub-agents, agent tools, workspace, voice, browser tools, retries, and more) ## Repository Structure | Directory | Description | | ----------------------------------------------------- | -------------------------------------------------------- | | [`packages/agents/`](packages/agents) | Core SDK | | [`packages/ai-chat/`](packages/ai-chat) | AI chat layer | | [`packages/think/`](packages/think) | Opinionated chat agent base | | [`packages/codemode/`](packages/codemode) | Code Mode | | [`packages/shell/`](packages/shell) | Sandboxed execution + filesystem | | [`packages/voice/`](packages/voice) | Voice pipeline | | [`packages/worker-bundler/`](packages/worker-bundler) | Runtime Workers bundler | | [`packages/hono-agents/`](packages/hono-agents) | Hono integration | | [`examples/`](examples) | Self-contained demo apps | | [`experimental/`](experimental) | Work-in-progress experiments (not published) | | [`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. pnpm workspaces with [Nx](https://nx.dev) for task orchestration, caching, and affected detection. ```sh pnpm install # install all workspaces pnpm run build # build all packages (Nx, cached, dependency-ordered) pnpm run check # sherif + export checks + oxfmt + oxlint + typecheck pnpm run test # vitest + vitest-pool-workers (Workers runtime) pnpm run test:react # Playwright-based React hook tests pnpm exec nx affected -t build # build only what changed pnpm exec nx affected -t test # test only what changed ``` Changes to `packages/` need a changeset: ```sh pnpm exec 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) --- ## File: docs/index.md # Cloudflare Agents SDK Documentation Documentation is grouped by the package that owns it: - [`agents`](./agents/index.md) — Durable Object agents, state, routing, scheduling, sessions, MCP, and shared primitives - [`@cloudflare/think`](./think/index.md) — opinionated agent harness built on Agents, Codemode, and Shell - [`@cloudflare/codemode`](./codemode/index.md) — sandboxed code execution, tool providers, connectors, approvals, and snippets - [`@cloudflare/shell`](./shell/index.md) — durable workspaces and filesystem tools - [`@cloudflare/voice`](./voice/index.md) — voice agents, clients, audio pipelines, and provider contracts Each package listed above includes its own documentation under `docs/`. Other published packages use their package README as their documentation entry point. Package indexes name relevant dependency documentation by package path, for example `agents/docs/index.md` or `@cloudflare/codemode/docs/index.md`. ## 2. Official Technical Reference & Guides (cloudflare/docs) AMPProject.org [](https://travis-ci.org/ampproject/docs) ========================= You're looking at the source code of the official website of the AMP Project. Even if you don't plan on contributing, explore how we've built the site for a good example of how to build a canonical, responsive standalone AMP site. How to build the site --------------------- ### Install Install [Grow](http://grow.io) and npm dependencies: ```sh $ curl https://install.growsdk.org | bash $ npm install ``` ### Get a GitHub token or app id/secret The docs in the reference section of the AMP Project site are not part of this repository; instead they are read from the [amphtml GitHub repository](https://github.com/ampproject/amphtml) "source of truth." When building the site these docs are fetched via GitHub. Due to GitHub quotas this fetching will quickly fail unless additional information is provided in the request. This can be either a personal access token or an application id/secret. #### Personal access token 1. Request a GitHub [personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/). Since the docs are fetched from a public repository you only need to select the "public_repo" scope when creating the token. (It's a good practice to limit the token to the scope you need.) 2. In your shell export the generated personal access token as `AMP_DOC_TOKEN` #### Application client id and secret If you prefer not to use a personal access token, you can also create a GitHub application and use its id and secret. 1. Register for a [GitHub application](https://github.com/settings/applications/new) 2. In your shell export the application client id as `AMP_DOC_ID` and the client secret as `AMP_DOC_SECRET` ### Build ```sh $ grow build ``` This will generate a static, complete build of the site into the **build* folder. ### Develop Note: Be sure to run `grow build` at least once to pull in reference docs before running the following command. ```sh $ grow run ``` You can now open http://localhost:8080/ and continue working on the source files, then reload the page to see changes appear. Support ------- If you've found an error or inconsistency, please file an issue: https://github.com/ampproject/docs/issues Patches are encouraged, and may be submitted by forking this project and submitting a pull request through GitHub. License ------- All image and audio files except in folders "source/img/partners", "source/img/publishers" and "source/img/quotes" (including *.png, *.jpg, *.svg, *.mp3, *.wav and *.ogg) are licensed under the CC-BY-NC license. Images in the excluded folders are not licensed. All other files are licensed under the Apache 2 license. - - - Copyright 2015 Google, Inc. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.