Cloudflare Agents Starter: A TypeScript Template for AI Chat Agents on Workers

Who the Agents Starter Is For

The agents-starter targets developers who want to build an AI chat agent and deploy it on Cloudflare Workers without writing the infrastructure from scratch. The template provides a working chat UI, streaming AI responses, tool calling, scheduling, and WebSocket state management in a single repository that deploys to Cloudflare with one command.

The README describes it as a starter template, meaning it is designed to be forked and modified. The most impactful initial change, according to the README, is editing the system string in server.ts to give the agent a different personality or focus area. From there, developers replace the demo tools with real integrations and extend the UI.

The template uses Workers AI by default, which means no OpenAI or Anthropic API key is required. Workers AI runs on Cloudflare's infrastructure and is billed through the Cloudflare account. This is convenient for getting started but couples the deployment to Cloudflare from the outset.

Three Tool Execution Patterns

The template ships with three distinct tool execution patterns, each suited to a different interaction model. The first is auto-execute: the tool runs on the server without user interaction when the model decides to call it. The README's weather example shows this pattern.

The second is client-side: there is no execute function, and the browser provides the answer through an onToolCall callback in app.tsx. Timezone detection is implemented this way in the starter, because the browser knows the user's timezone without a server round-trip.

The third is approval: the tool has a needsApproval function that gates execution. The model requests the tool call, the UI shows a confirmation prompt, and the tool only runs after the user approves. The README shows arithmetic calculation as the approval example, illustrating that even low-risk operations can be gated.

The README shows the structure of each pattern in TypeScript:

// Auto-execute: runs on the server automatically
myTool: tool({
  description: "...",
  inputSchema: z.object({ /* ... */ }),
  execute: async (input) => { /* return result */ }
}),

// Approval: gates execution on user confirmation
sensitiveTool: tool({
  description: "...",
  inputSchema: z.object({ /* ... */ }),
  needsApproval: async (input) => true
})

All tools are defined in the tools object in server.ts. The README instructs adding new tools to the same object and handling client-side tools in app.tsx via the onToolCall callback.

Installing and Running the Template

The README's quick start creates a new project from the template:

npx create-cloudflare@latest --template cloudflare/agents-starter
cd agents-starter
npm install
npm run dev

The important caveat appears in the README: Cloudflare authentication is required to run locally. Workers AI has no local simulator, so npm run dev opens a remote proxy session against Cloudflare's infrastructure. Either run wrangler login once in an interactive terminal, or set a CLOUDFLARE_API_TOKEN environment variable before running dev.

Deployment runs through npm run deploy, which calls vite build and then wrangler deploy. The Worker's URL is derived from the name field in wrangler.jsonc: it deploys to name.subdomain.workers.dev.

After running, the README suggests testing with specific prompts: asking for weather in Paris exercises the server-side tool, asking for your timezone exercises the client-side tool, asking for a calculation exercises the approval tool, and scheduling a reminder exercises the scheduling feature.

Scheduling and WebSocket State

The template includes a task scheduling system with three modes: one-time, delayed, and recurring (cron). Scheduled tasks are defined through tools and fire via the executeTask method on the server. When a task fires, the agent does the actual work and then calls this.broadcast() to notify connected clients.

The README explains a design decision around broadcast versus saveMessages: injecting the notification into chat history would cause the AI to see it as new context and potentially re-trigger the same task in a loop. The broadcast approach sends a one-off event that the client displays separately from the conversation history.

The README shows how to customize executeTask for a real use case:

async executeTask(description: string, task: Schedule<string>) {
  await sendEmail({ to: "[email protected]", subject: description });
  this.broadcast(
    JSON.stringify({ type: "scheduled-task", description, timestamp: new Date().toISOString() })
  );
}

If scheduling is not needed, the README documents how to remove it: delete the scheduleTask, getScheduledTasks, and cancelScheduledTask tool definitions, the executeTask method, and the schedule-related imports.

For state beyond chat messages, the template uses this.setState() and this.state for real-time state synchronized across connected clients. The WebSocket connection includes automatic reconnection and message persistence.

Switching AI Providers: OpenAI and Anthropic

The README documents how to replace Workers AI with a different provider. For OpenAI, install the SDK and update the model in server.ts:

npm install @ai-sdk/openai

For Anthropic, the process is the same structure with a different import:

npm install @ai-sdk/anthropic

Both require creating a .env file with the relevant API key and updating the streamText call to use the new model.

The template also supports MCP server connections, adding tools from external MCP servers to the agent's tool set:

await this.mcp.connect("https://my-mcp-server.example/sse");
const result = streamText({
  tools: { ...myTools, ...this.mcp.getAITools() }
});

Callable methods (annotated with @callable() from the agents package) expose typed RPC endpoints that the client can call directly, separate from the AI conversation loop.

Limitations and When Not to Use the Template

The most significant constraint is the local development requirement for a Cloudflare account. The README makes this explicit: there is no local Workers AI simulator. A developer without a Cloudflare account or without internet access during development cannot run npm run dev. This is a departure from most Node.js frameworks where local development is fully offline.

The template is a starter, not a framework. It demonstrates patterns but does not enforce architecture. Teams that need a durable persistence layer beyond the WebSocket state, complex multi-tenant isolation, or fine-grained observability on AI calls will need to add those layers.

The comparable alternative for teams that want more infrastructure flexibility is building on top of LangChain.js deployed on Vercel, which supports multiple AI providers, has a local development path that does not require a provider account, and runs on standard Node.js. The tradeoff is that LangChain.js is a larger abstraction layer with more moving parts; the agents-starter is closer to the underlying platform primitives.

The last push to this repository was on 2026-08-19. The package.json lists agents at version 0.17.4 as the core dependency for the Agents SDK, and wrangler at 4.113.0. The project is MIT-licensed.

Editorial conclusion

The agents-starter is a well-structured starting point for developers who want to deploy an AI chat agent on Cloudflare Workers without setting up an external AI provider. The Workers AI default removes one credential requirement at the cost of locking local development to a live Cloudflare connection. Teams who need fully offline local development, or who want to avoid vendor lock-in on the hosting layer, will find the template useful as a structural reference but will replace significant parts of the implementation. Verify that your Cloudflare plan covers the Workers AI usage you expect before committing to the architecture.

Frequently asked questions

Official sources

1. cloudflare/agents-starter on GitHub
2. Issues
3. License: MIT
4. Project website
5. README