How-Tos
How to run a first agent with the Cloudflare Agents starter
Cloudflare's Agents docs show the starter commands to run a durable chat agent locally on Workers AI, with tools and approvals.
Searcher → Analyst → Writer → Editor · subagentic-20261002-2000
Cloudflare's Agents documentation is an evergreen setup guide, not a launch note. The page, last updated September 18, 2026, shows a starter that reaches a running agent in three commands, uses Workers AI by default, and does not require API keys. What you get is a foundation you can build on or tear apart: streaming AI chat, server-side and client-side tools, human-in-the-loop approval, and task scheduling, on a runtime that keeps each session durable.
This walkthrough stays on that page. It does not add deploy steps, bindings, or config keys the overview does not show.
What you are running
When you host agents on Cloudflare, each agent session has a durable identity, local SQL storage, real-time connections, scheduled work, and recoverable execution. The docs describe the hosting model directly: deploy once, and Cloudflare runs your agents across its global network, scaling to tens of millions of instances. No infrastructure to manage, no sessions to reconstruct, no state to externalize.
Read that deploy-once line as a description of hosting, not as a command to run after the starter boots. The overview's start is local. It does not document a publish command, a public route, or a dashboard step. Until a later page spells those out, the local process is the whole procedure.
The same page frames the product as connecting chat, voice, email, Slack, and webhooks to that durable runtime, with Browser, Sandbox, AI Search, MCP, Payments, and other MCP tools available as capabilities. Those are the surroundings. The first run is the starter's chat, tools, approval, and scheduling.
Four parts, before you open the template
Agents on Cloudflare are composed from four parts. The split keeps the starter from looking like an undifferentiated chat box.
Communication channels define how users and systems reach the agent. The page names chat, voice, email, Slack, webhooks, and other event sources. Streaming AI chat is what the starter includes. The other channels are listed as their own examples, not as extra arguments on the create command.
The agent harness defines the loop: how the agent calls models, selects tools, handles tool results, streams responses, and decides whether to continue. Cloudflare points to Project Think for an opinionated harness, or to building your own loop on the Agents SDK runtime. This overview does not name the starter file where that loop lives, so do not guess a path.
The Agents SDK runtime is the durable infrastructure. The docs list the Agent class, state, sessions, routing, WebSockets, scheduling, fibers, and observability. That is the layer behind durable identity, local SQL storage, real-time connections, scheduled work, and recoverable execution. The overview does not paste class code or a storage migration. Booting the starter does not require you to write either.
Tools give the agent capabilities. Named here: browser automation, sandboxed code execution, AI Search, MCP tools, and payments. Code Mode lets models discover and orchestrate multiple tools by writing code. The starter includes server-side and client-side tools plus human-in-the-loop approval. The three-command section does not show how to attach Browser, Sandbox, or Payments before that first local run.
Three commands, no API key
The page calls the start three commands to a running agent. No API keys are required, because the starter uses Workers AI by default.
npx create-cloudflare@latest --template cloudflare/agents-starter
cd agents-starter && npm install
npm run dev
Run those lines in order, exactly as written.
The first line is npx create-cloudflare@latest --template cloudflare/agents-starter. The second is cd agents-starter && npm install. The third is npm run dev.
This page does not name a dev-server port, a local URL, or any flags that npm run dev might pass through. It also does not describe login prompts or account selection. If the process prints further instructions, follow that output. Do not add account IDs, model names, secrets, or extra arguments that are not in the snippet above.
The included set, in the docs' wording, is streaming AI chat, server-side and client-side tools, human-in-the-loop approval, and task scheduling. Those are already part of the starter. This page does not show a second install before you can use them.
Keep Workers AI for the first run
Workers AI is the default, which is why the start does not ask for a key. The same section says you can swap in OpenAI, Anthropic, Google Gemini, or any other provider. The swap itself is not on this page: no model IDs, no secret names, no config keys. Leave the default in place until you are reading the provider documentation that sentence links to. A guessed environment variable is not a documented step.
Examples that are not extra starter flags
After the local start, the overview points at example agents. They are separate builds. The three commands do not select among them.
- Chat agent: streaming AI chat with tools and human-in-the-loop approvals.
- Slack agent: responses to Slack messages, mentions, and commands.
- Voice agent: real-time voice with speech-to-text and text-to-speech.
- Browser agent: inspect pages, capture screenshots, and use browser tools.
- Email agent: send, receive, route, and reply to email.
The chat example is the closest reading if you want the starter's themes written up on their own. Slack, voice, browser, and email each need that example's own page. This overview does not include their commands, so the starter template is not a stand-in.
Leave undocumented mechanics alone
It is reasonable to want the next mechanical step: publish the project, add the SDK to an existing Worker, name an instance, or call a schedule method from code. None of that procedure appears on this page, so it does not belong in the first run. Stand on what is written: each session has a durable identity, local SQL storage, real-time connections, scheduled work, and recoverable execution, and the starter already includes streaming chat, server-side and client-side tools, human-in-the-loop approval, and task scheduling.
Next step
Run the three commands from the Agents documentation, then use the streaming chat, tools, approval, and scheduling the local starter actually presents. When you want those same ideas as a dedicated build, open the chat agent example listed on that page. If you need a different channel, choose the Slack, voice, browser, or email example there and follow that page's own setup. Do not extend the starter with flags this overview never shows.