Writing by Kai Bitterschulte

AI on Cloudflare: a decision guide

2026-10-07T00:00:00Z

This guide covers which Cloudflare products to put in place for AI, and in which order.

Every AI setup has the same shape: someone acts, the AI runs in a session, it reaches models, tools and private systems through gates, and everything is logged. Step 1 starts with that picture.

Start with two questions

Do you build AI yourself, or use AI that someone else built? And who is affected, your customers or your employees? The answers give four cases.

The four cases, A to D. Step 1 lists the products to put in place for each one, in order.

The reading path

Step 1: Cloudflare and AI: choose your path. The four cases, which product guards which AI traffic, where models and agent-written code run, how to govern agents inside your company, and when Cloudflare OS fits.
Step 2: Building AI agents on Cloudflare: which architecture when. For cases A and B. Ten ways to build an agent, from a plain Worker to Project Think and VibeSDK, with starter code.
Reference: the decision matrix. The building blocks each situation needs, on one page.

Shortcuts by situation

Your situation	Read first	Then
A. Your customers use AI that you built (a chatbot or AI search in your product)	A2: the control map and A3: where inference runs	Step 2, then the matrix row A
B. Your staff use internal AI that you build (agents for engineers and IT, an internal assistant)	A4: the governed agent workspace and A6: Cloudflare OS and A7: VibeSDK	Step 2, then the matrix rows B1 to B4
C. Your staff use third-party AI (ChatGPT, Claude, Gemini, coding assistants)	A2: the control map, control C4	The matrix row C. Nothing to build, so skip step 2.
D. AI visits your sites (crawlers and agents reading your content)	A2: the control map, control C5	The matrix row D. Nothing to build, so skip step 2.

Every product claim links to the public Cloudflare documentation, and experimental, beta and paid add-on features are marked. I built the guides from the documentation and checked them on 7 October 2026, but I have not deployed every option. Feature status changes, so check the linked page before you commit to a design.

Cloudflare and AI: choose your path

2026-10-07T00:00:00Z

Most conversations about AI and Cloudflare start with a product name. It helps to start with the shape of the setup. Then you can see which parts your case needs and which Cloudflare product covers each one.

The shape of every AI setup

The same shape for every setup: one gate in front of the session and one on every exit. The row at the bottom covers what comes in from outside.

Someone acts, and Access checks who it is. The AI runs in an isolated session or in your own app. From there it reaches models, tools and private systems, and each exit gets one gate. Every model call, tool call and connection is logged with the user and the policy.

Three things sit at the edge of this picture: prompts that arrive from the internet, staff who use AI apps you did not build, and AI crawlers that read your sites. The four cases below differ in which of these parts you have to deal with.

A1. Step 1: what kind of AI question is this?

Two questions sort your situation into four cases: do you build AI yourself or use AI that someone else built, and who is affected, your customers or your employees. Each case lists the Cloudflare products to put in place, in order.

The four cases. A product that calls a hosted model API is still case A, because you build the product. A3 covers where the model runs.

Case	What the customer says	Put in place, in this order	Then
A. AI in your product	"We added a chatbot or AI search to our app." "We worry about prompt injection and PII in prompts."	1. Find the AI endpoints (LLM endpoint discovery). 2. AI Security for Apps detections in WAF rules. 3. AI Gateway between app and model for logs, limits and fallback. 4. Normal WAF, Bots and API protection.	Build with Part B or a plain Worker. If users should build apps inside your product: VibeSDK (A7).
B. Internal AI you build	"We want agents for our engineers and IT." "Our staff need an assistant on our data."	1. Access in front, with your identity provider. 2. All model calls through AI Gateway. 3. Tools through an MCP server portal. 4. DLP. 5. Private reach over Tunnel, Mesh or Workers VPC. 6. Isolated execution.	A ready-made start: Cloudflare OS (A6), or VibeSDK if staff should build apps (A7). Or build: Part B for the agent, A4 for the governed workspace pattern.
C. Staff use third-party AI	"People paste code and customer data into ChatGPT." "We cannot see which AI tools are used."	1. Shadow IT dashboard and CASB for visibility. 2. Gateway HTTP policies, including actions inside AI apps. 3. DLP profiles on prompts and uploads. 4. Sanctioned tools behind Access.	Nothing to build. Offer a sanctioned path.
D. AI visits your sites	"AI crawlers take our content." "Agents hit our APIs."	1. AI Crawl Control: see which AI services access your content. 2. Allow or block per crawler, check robots.txt compliance. 3. Bots and rate limiting for the rest.	Optional: pay per crawl (private beta).

A2. The control map: which product guards which traffic

The picture above shows where each control sits. Calls to models go through AI Gateway and calls to tools through MCP server portals. AI Security for Apps checks prompts from the internet, Gateway, CASB and DLP cover staff who use AI apps, and AI Crawl Control covers AI crawlers. Access checks who is acting, and DLP and logs apply to all of them.

Pick what you want to control. The table below has the details.

Control	Guards	Key facts from the docs	Watch out
C1. AI Gateway	Calls from apps and agents to model providers.	A proxy with analytics, logging, caching, rate limiting, retry and model fallback. Available on all plans. Guardrails evaluate prompts and responses and can flag or block by category. DLP scans prompts and responses without Gateway HTTP filtering or TLS decryption.	It covers only traffic you route through it. To force that, also block direct provider endpoints.
C2. MCP server portals	Tool calls from MCP clients to internal and SaaS MCP servers.	One endpoint for many servers. Admins choose tools and prompts per portal, rename them with aliases, and can enable Code Mode (two tools, JavaScript run in a Dynamic Worker). Access logs each tool request. Private servers work through Tunnel with Gateway routing turned on.	Independent MFA, purpose justification and temporary authentication are not enforced for servers authorized through a portal. Blocked users can still reach a server by its direct URL unless Access is its OAuth provider.
C3. AI Security for Apps	Prompts sent from the internet to your own LLM-backed endpoints.	Model-agnostic. Detects prompt injection, PII and unsafe or custom topics in requests to endpoints labeled `cf-llm`, JSON only. Results become WAF fields for custom or rate limiting rules. LLM endpoint discovery is on all plans.	The detection fields and log mode ruleset are a paid add-on on Enterprise. Formerly called Firewall for AI.
C4. Gateway, Shadow IT, CASB, DLP	Employees using third-party AI apps.	The holistic AI security learning path names the Shadow IT dashboard and API CASB for visibility, Gateway policies to allow, block or redirect, and DLP for data loss. HTTP policies can control specific actions inside AI apps. CASB has API integrations for ChatGPT, Claude and Gemini (changelog, August 2025).	HTTP policies need the Cloudflare root certificate or a custom certificate on the device. DLP is an add-on to Zero Trust Enterprise.
C5. AI Crawl Control and Bots	AI services reading your content.	A dashboard of crawler activity, allow or block per crawler, robots.txt compliance and enforcement rules. All plans. Formerly AI Audit.	Pay per crawl is in private beta.

Control map for AI traffic: what each control sits in front of.

Sandboxes and Code Mode keep agent-written code away from your credentials.

AI security on Cloudflare: one identity from login to tool call.

A3. Where does inference run?

Where the model runs decides where your data goes, what it costs and who operates it. AI Gateway and Access work with all three options.

Select where the model runs.

Option	Use when	Data boundary	You operate
I1. Workers AI	You want models without API keys, billed on Cloudflare, called through the AI binding.	Stays on Cloudflare.	Nothing.
I2. Hosted providers through AI Gateway	You need frontier models from OpenAI, Anthropic, Google and others, with one place for logs, limits and fallback.	Prompts go to the provider, with gateway guardrails and DLP in between.	Provider keys and routing rules.
I3. Private inference on hardware you own	Some work must not leave the company boundary, or you want to use idle machines as low-cost capacity.	Prompts stay on your network, reached over private routes.	The machines, model serving and capacity.

The idea of a local inference mesh

Your company may own idle computers: developer Macs, GPU workstations, spare servers. A mesh can join them into one pool of private model capacity. Agents call one controlled entry point, and a router picks where each request runs. Sensitive work runs on the private nodes, so sensitive prompts never leave the company network. Idle hardware takes over part of the work that would otherwise go to hosted models. Hosted providers stay as the default or fallback, so a busy mesh does not stop work.

A local inference mesh behind one gateway.

Three Cloudflare pieces make it governable:

AI Gateway is the front door. It applies identity, budgets, guardrails, DLP and logs to every route, private or hosted.
Cloudflare Mesh gives each enrolled server or laptop a private Mesh IP and lets nodes advertise routes. Zero Trust policy decides who can reach which node.
AI Gateway custom providers connect models that have an HTTPS API endpoint, including self-hosted models, so the same logs, limits and guardrails apply.

I do not cover how the gateway reaches the private machines (Mesh, Tunnel or Workers VPC, which is in beta). Check the network path for your setup.

A4. Internal IT and engineering: the governed agent workspace

This is the shape from the start of this part, built out for case B. Engineers and operations staff work with AI agents that change code and infrastructure, under rules your company sets. It combines the controls from A2 around one session, with one gate in front and one on every exit.

A governed agent workspace: one gate in, one gate on every exit.

Your engineers may already use agents. Without a sanctioned path they use personal keys and tools, and central IT has no log, budget or policy. A governed workspace sets identity, model access, tool access and network reach once, not per laptop and per tool. An agent that patches servers or changes a firewall needs a limited route and an approved plan. Changes go through your own git, CI and branch protection, and a person approves the merge or the change.

Element	What it does	Built from	Docs
Session entry	The user signs in through your IdP. A browser session means nothing is installed on the laptop.	Access in front of the workspace, with device posture checks.	Access
Isolation	Each session runs in an isolated environment in your own account, removed on exit.	Sandboxes (a Container, which is a Linux microVM, or a Dynamic Worker) or Containers.	Sandboxes
Agent harness	Runs the loop, keeps memory, delegates to sub-agents.	Think, AIChatAgent or your own loop (Part B), or an existing coding agent.	Agents
Model access	Model calls go through the gateway. Provider keys are stored in the gateway, prompts are scanned, and each request carries the verified Access user ID.	AI Gateway behind Access, stored keys, guardrails and DLP. Gateway policies can block direct provider endpoints.	AI Gateway with Access, stored keys
Tools	Agents get only the tools their role allows. Large tool sets collapse into a code tool.	MCP server portals with per-portal tools and Code Mode.	MCP server portals
Reach	Internal hosts, databases and control planes are reachable only on routes the user's group is allowed.	Zero Trust client with private routes over Mesh or Tunnel.	Mesh
Change control	Changes flow through git, CI and branch protection, then reviewer agents, then a human approval.	Your own git and CI.	Not a Cloudflare product
Evidence	Every model call, tool call and connection is logged with user and policy.	AI Gateway logs, Access and Gateway logs, Logpush to a SIEM.	AI Gateway Logpush, Zero Trust logs
Private inference	Optional private model capacity on idle machines, behind the same gateway.	AI Gateway custom providers plus a private route (Mesh), see A3.	Custom providers

The harness is a Part B decision. Think suits a stateful chat or operations agent. AIChatAgent or your own loop suit cases where you must control the model call. Patch rollouts and reviews are long tasks that must survive restarts, so a Workflow fits the approved, repeatable part: rollout in batches, rescan, close the ticket.

Each gate protects only what passes through it. To control model egress, also block the direct provider endpoints. Start read-only for infrastructure agents and give write access per task, behind an approval step. Keep the human merge and the human approval of infrastructure plans.

A5. Where does agent-written code run? The execution ladder

When an agent writes and runs code, use the lightest environment that does the job.

Select where agent-written code runs.

Step	Use when	What it is	Watch out
E1. Code Mode	The agent has many tools, or an API with many operations, and loses context to tool definitions.	The model gets one code tool and writes JavaScript that calls typed tool methods. In MCP server portals it replaces all upstream tools with a search tool and an execute tool.	Experimental and may introduce breaking changes.
E2. Dynamic Workers	You must run code you do not trust, written at runtime.	Isolated Workers created on demand. You control their bindings and whether they reach the network. A lightweight alternative to containers.	Runs JavaScript, WebAssembly and (with a compatibility flag) Python. It has no Linux shell. Open beta since March 2026 on Workers Paid. Check the current status.
E3. Sandboxes	The agent needs a shell, repos, package installs or test runners.	An isolated place to run code, either a Container (a Linux microVM) or a Dynamic Worker, reached through your Worker. Your Worker decides what data and APIs the code gets and whether it reaches the Internet.	Workers Paid plan. The docs list separate Sandbox SDK versions. Check which one you use.
E4. Containers	A workload needs many CPU cores, lots of memory, a specific runtime or an existing container image.	Serverless containers started and controlled by a Worker.	Use them directly for your own workloads. As a sandbox, a Container is the Linux option.
E5. Browser Run	The target is a website without an API.	Headless Chrome on the Cloudflare network (formerly Browser Rendering): markdown, screenshots, PDFs, scripted interaction.	Treat fetched page content as untrusted input to the model.

A6. A ready-made start: Cloudflare OS

Cloudflare OS is an open-source agent workspace for everyone in a company, including people who do not code. You deploy it into your own Cloudflare account and adapt it. It is case B as a finished starting point, with four parts.

Select what you need: Cloudflare OS or another path.

Agent workspace. Each person works in the browser with an agent that knows your company context and shared skills. The agent writes and runs code in an isolated runtime.
Gadgets. The agent can build small apps for one person or one team. Each app runs in its own Dynamic Worker with its own database and can be shared like a document.
Gatekeepers. A Gatekeeper sits between the workspace and one external service. It limits access to the resource you chose, logs every action and asks a person to approve actions with side effects.
Workflows. Repeatable jobs run on demand, on a schedule or when an event happens in a connected system.

Control	What Cloudflare OS does	Matches in this guide
Identity	Cloudflare Access controls who can enter. Inside, every agent and app starts with access to nothing and asks for each resource.	A2, identity
Model calls	Every inference call runs through AI Gateway, attributed to a person, team or workspace, with budgets and rate limits. Any model can be used, including self-hosted ones.	C1, I1 to I3
Tool calls	Gatekeepers give scoped access to single resources. Existing MCP servers connect through MCP server portals.	C2
What the agent has seen	The platform records which resources agents observed. It uses this to decide who may open the workspace or see its output, and when an agent may send data out.	Not covered by the other controls
Code execution	The agent works by writing code. Server code runs in a Dynamic Worker with outbound internet disabled. Client code runs in a sandboxed frame.	E1, E2
Not covered in the public sources	DLP, private network reach over Mesh or Tunnel, and export of logs to a SIEM. Plan these with the controls in A2.	C4, A4

It fits a workspace for all staff, including people who do not code, with shared skills and company context for every agent and small internal apps that people build and change themselves.

It is early access, and the README says it still has "many rough edges". Running it on your own servers with workerd is listed as "coming soon". A managed version in the Cloudflare dashboard, containers for development workflows and Slack support are planned. For customer-facing AI or shell-heavy engineering agents, see Part B and A4.

See also the GitHub repository and os.cloudflare.app.

A7. Another ready-made start: VibeSDK

VibeSDK is an open-source (MIT) platform where people build and deploy full-stack apps by describing them to an AI coding agent. The README calls it "an open-source vibe coding platform that helps you build your own vibe-coding platform". It is a starting point for case A (your customers build apps inside your product) or case B (internal teams such as marketing, product and support build their own tools, as the launch post describes it).

According to the README, a session works like this:

The user describes the app. The agent asks structured questions when the request leaves something open.
The agent plans, edits files, deploys a preview, reads the browser console, repairs errors and repeats, while the user follows along.
Each project has its own workspace and version history with restore points. The finished project can be exported to continue elsewhere.

Part	What it does	Docs
Think agent	Runs the model-and-tool loop. It uses explicit tools to read and edit the workspace, deploy previews and inspect browser logs. Bash access is disabled.	Think
Workspace	A Durable Object per project holds the files.	Durable Objects
Previews	Generated code is bundled and loaded as a Dynamic Worker, with no long-running development server.	Dynamic Workers
App data	Each generated app has isolated SQLite storage in a Durable Object Facet.	Durable Objects
Version history	Cloudflare Artifacts stores git history and restore points. It is an optional setting in the README.	Artifacts
Model calls	Configured providers are routed through AI Gateway, with observability and caching.	AI Gateway

Control	What VibeSDK does	Matches in this guide
Model calls	Routed through AI Gateway, with observability and caching.	C1, I2
Code execution	Previews run as Dynamic Workers. The agent has no bash access to the workspace.	E2
Isolation	Each project has its own agent, workspace, repository and app storage. Preview URLs are signed and limited to one branch.	A4
Identity	Authentication providers are optional and configuration-dependent. The README does not describe Access.	A2, identity
Not covered in the README	DLP, Gateway policies for staff, private reach over Mesh or Tunnel, and export of logs to a SIEM. Plan these with the controls in A2.	C4, A4

It fits a platform where people who do not write code build small apps, a SaaS product that lets customers build their own customisations, or a base that you fork and change. It builds and hosts apps. To govern the coding agents your engineers already use, see A4. Cloudflare OS gives each person an agent workspace, while VibeSDK turns descriptions into deployed apps.

The reference architecture calls it a starter template, and I found no support or maturity statement for VibeSDK itself in the README. It builds on features that are still maturing: Think is experimental, Dynamic Workers entered open beta in March 2026, and Artifacts is in open beta (changelog, 1 October 2026). For production, the README lists a Workers Paid plan, Workers for Platforms access for production previews, a custom domain with wildcard DNS (and Advanced Certificate Manager where the layout needs it), and credentials for at least one model provider. The September 2025 launch post describes an earlier design with Sandboxes and Workers for Platforms. The README describes the current design.

Building AI agents on Cloudflare: which architecture when

2026-10-07T00:00:00Z

Project Think, the Agents SDK, the AI SDK, Workflows, MCP servers and a plain Worker work at different layers.

The AI SDK is a library for calling models.
The Agents SDK is the runtime that keeps an agent alive: state, wakeups, crash recovery.
Think and AIChatAgent are harnesses that run the loop on top of that runtime.
Workflows and MCP sit beside the agent.

1. Decision tree: what should I build?

The coloured boxes are the recommendations. Section 6 covers combinations.

Does the model choose the next step itself, looping over tools?

The model does not choose the path. For several fixed steps that need retries or human approval, use a Workflow. Otherwise use a plain Worker with one model call.
The model loops over tools and you already use a harness such as Claude Code, opencode or Codex. Keep it and secure it (see A4 in Part A). If that harness needs your tools or data, expose them with an MCP server behind a portal.
You want a finished platform that you adapt. Use Cloudflare OS for a staff workspace (Part A, A6) or VibeSDK for a platform where users build apps (Part A, A7).
You build your own loop. If you need no memory or wakeups, use a Worker with the AI SDK. If you need memory per user, wakeups or tasks longer than a request, and you want a ready-made loop, use Project Think. With the same needs, if you want to own the model call and have a chat UI, use AIChatAgent. If it is not a chat (inbox, monitor, webhook), use the Agent class.

2. The stack: which layer is which

AIChatAgent is built on the AI SDK. The docs describe the AI SDK as "what AIChatAgent and the starter template use under the hood". The runtime answers "where does this agent live and how does it stay durable". The harness answers "what does this agent do on each turn".

The layers: surfaces, harness, runtime, optional gateway, models.

3. Ten architectures, side by side

A. Plain Worker with Workers AI or the AI SDK

A normal Worker calls a model. It has no state and no runtime.

Use when: one prompt gives one answer (summarise, classify, extract, rewrite), or a short tool loop fits in one request.
Skip when: you need memory, wakeups or work that outlives a request.
You write: the handler, prompt, tools and any storage.
You get: the lowest cost and complexity. You can use any AI SDK provider or the env.AI binding with no API key.
Docs: Using AI models

B. Workflow with LLM steps

Code defines the path and the model is one step in it. Each step is saved and retried on its own.

Use when: the steps are known in advance (onboarding, document pipelines, deploys, reports) and you want retries per step and human approval.
Skip when: the model has to decide the path. Then you need an agent.
You write: the step code, the workflow class and its config.
You get: per-step retries with backoff and a built-in waitForApproval().
Docs: Agents with Workflows, Workflows versus agent-internal patterns, Workflows limits

C. Agent class, your own harness

The runtime without a built-in loop. You get a durable identity and wakeups, and you write what happens each turn.

Use when: you need control of the loop or the wire format, or the agent is not a chat: an inbox processor, a monitor, a reminder bot or a webhook handler.
Skip when: you only need a chat UI with memory. Think or AIChatAgent do that.
You write: the turn logic, prompt building, tool calling and message storage format.
You get: synced state, SQLite, WebSockets, four kinds of schedule, crash recovery and sub-agents.
Docs: Agents API, Schedule tasks, Durable execution with fibers

D. AIChatAgent

A protocol adapter for chat. It stores messages, streams, resumes and handles tools. You write the model call.

Use when: you want full control of the model call in a chat product (RAG, several models, custom streaming), or a simple chatbot without memory.
Skip when: you want memory blocks, history search and non-destructive compaction out of the box. Think has these.
You write: about 15 lines: streamText, tools, system prompt, return the response.
You get: SQLite message storage, resumable streams, tool support including approvals, durable chat recovery.
Docs: Chat agents

E. Project Think

A harness with a fixed structure. You pick the model, and Think runs the loop, memory, tools and recovery.

Use when: you want to ship fast with persistent memory, long conversations, history search, sub-agents or proactive turns from schedules and webhooks.
Skip when: you must own the exact LLM call or message format. Use AIChatAgent or the Agent class. Think is still experimental.
You write: getModel(), three lines for a first agent. You override single pieces such as the system prompt or tools later.
You get: a branching message tree, memory blocks the model can write, FTS5 search, non-destructive compaction, workspace tools, extensions and durable recovery.
Docs: Think, Harnesses, announcement

F. MCP server on a Worker

You expose tools, and the client's AI app is the agent. There is no loop on your side.

Use when: any MCP client should use your system, such as an internal API, a firewall or a SaaS. The model and the loop live in the client.
Skip when: you need your own agent with memory and a schedule. Build C, D or E and let it call MCP servers as a client.
You write: tool definitions with good descriptions. Few task-shaped tools work better than many thin ones.
You get: streamable HTTP transport, OAuth or Access for login, testing with MCP Inspector.
Docs: Build a remote MCP server, Handler APIs

G. Orchestrator with sub-agents

One agent coordinates and several children do focused work. Each child has its own SQLite and typed RPC.

Use when: work splits into specialised roles, or one parent manages many long-lived child contexts (per customer, project or task).
Skip when: one agent with a few tools is enough. Every extra agent adds coordination and debugging cost.
You write: the delegation logic. Children are classes, called by typed RPC.
You get: isolated storage per child, streaming turns through chat(), and children usable as tools with retained runs and abort.
Docs: Sub-agents, Agents as tools, Think sub-agent RPC

H. Existing harness, secured

Your team already uses an agent such as Claude Code, opencode, Cursor or Copilot, and you control what goes in and out.

Use when: IT must govern the coding or chat agents your staff already use (keys, data loss, tool access, audit), or you expose your own tools to them.
Skip when: you need your own memory model, proactive wakeups or a customer-facing agent.
You write: policy only: AI Gateway for model requests (gateway token or an Access-protected custom domain), the MCP server portal as remote MCP server, DLP and Gateway rules.
You get: per-user logs and budgets, scanned prompts, tools limited per portal and provider keys in the gateway instead of on laptops. The docs have setup guides for coding agents such as Claude Code, OpenAI Codex and OpenCode.
Docs: Coding agents through AI Gateway, AI Gateway with Access, MCP server portals. See A4 in Part A.

I. Cloudflare OS, the finished workspace

An open-source workspace for all staff that you deploy in your own Cloudflare account.

Use when: you want a workspace for all staff, including people who do not code: agent chat, shared skills, small apps and workflows.
Skip when: you need a supported product today (it is early access), you build AI for your customers, or you need shell-heavy engineering agents.
You write: configuration: Access policies, AI Gateway setup, Gatekeepers, your skills and context.
You get: open source (Apache-2.0) with an agent workspace, gadgets, Gatekeepers, inference through AI Gateway and MCP server portal support. See A6 in Part A.
Docs: launch blog post, GitHub, os.cloudflare.app

J. VibeSDK, the app-building platform

An open-source platform where users describe an app and an AI coding agent builds, previews and deploys it.

Use when: people should build apps by describing them: customers inside your product, or internal teams building their own tools.
Skip when: you need to govern coding agents your engineers already use (option H), a workspace for all staff (option I) or a supported product today. The README has no support statement.
You write: deployment and configuration: model providers, the domain, project templates and any agent customisation.
You get: open source (MIT) with a Think-based agent loop, a workspace per project, previews as Dynamic Workers, isolated SQLite storage per generated app, optional version history in Artifacts and model calls through AI Gateway. See A7 in Part A.
Docs: GitHub and README, setup guide, launch post, reference architecture

4. Comparison at a glance

Option	Memory and state	Who runs the loop	Wakes on its own	Survives a crash or deploy	Code to start	Watch out
A. Plain Worker + AI SDK	None built in. Bring your own storage.	The AI SDK, for example a tool loop capped with `stopWhen`.	No, only when something calls it.	Request scoped. You handle retries.	About 10 lines.	Not an agent with memory. Fine for single calls.
B. Workflow	Step results persisted by the workflow engine.	Your code defines the steps. The model runs inside a step.	Sleeps and waits inside a run. Started by a trigger or an agent.	Per-step retries with backoff, resume after failure.	A separate class plus config.	The path is fixed in code.
C. Agent class	SQLite per agent, state synced to clients.	You.	Yes: delayed, date, cron and interval schedules, plus email and webhooks.	Fibers with `stash()` checkpoints and `onFiberRecovered`.	A small class, plus the harness you build.	In-memory variables and timers do not survive eviction.
D. AIChatAgent	Messages in a flat SQLite table. `maxPersistedMessages` deletes the oldest.	You, inside `onChatMessage`.	Yes, it extends Agent.	Durable chat recovery is always on.	About 15 lines.	Forward `abortSignal` to `streamText` or cancelled calls keep running.
E. Think	Session tree, memory blocks the model writes, FTS5 search, non-destructive compaction.	Think. You override single hooks.	Yes: scheduled tasks, webhooks through submitted turns.	Durable recovery, stream-stall watchdog.	Three lines: `getModel()`.	Experimental. The API may still change.
F. MCP server	Stateless handler for new servers.	The client, for example Claude or Cursor.	No.	Stateless, so nothing to recover.	A template or the `mcp-worker` example.	Needs auth. Quick-deploy templates still use the deprecated `McpAgent`.
G. Sub-agents	Own SQLite per child, isolated.	The parent delegates, children run their own turns.	Children can schedule. The parent owns the physical alarm.	Fibers work inside children too.	A class per role.	More agents mean more coordination to debug.
H. Existing harness, secured	Whatever the existing tool keeps. Policy and logs live in the gateway.	The existing agent.	Depends on the tool. The controls do not add wakeups.	Not provided by the controls.	Policy, not code.	Controls only see traffic routed through the gateway or portal. Block direct provider endpoints too.
I. Cloudflare OS	Each workspace is a Durable Object. Each gadget has its own SQLite database.	Its built-in Code Mode agent.	Workflows run on demand, on a schedule or on events.	Not stated in the public sources.	Configuration, not the agent.	Early access with rough edges. The managed dashboard version is planned.
J. VibeSDK	A Durable Object workspace per project. Each generated app has its own SQLite storage.	Its Think agent.	Not stated in the README.	Not stated in the README.	Deployment and configuration.	Reference implementation with no support statement. Builds on experimental and beta features.

5. How to create each one

These are the smallest working setups per option. The snippets come from the linked docs or are adapted from them, and I have not deployed every one. At the time of writing, @cloudflare/think 0.20 and workers-ai-provider 4 require AI SDK v7 (ai ^7); older Think versions also accepted v6. Keep the AI SDK packages on matching major versions and check the current versions before you install.

E. Project Think: the fastest start for a stateful chat agent

npm i @cloudflare/think @cloudflare/ai-chat agents ai @cloudflare/shell zod workers-ai-provider

src/index.ts:

import { Think } from "@cloudflare/think";
import { createWorkersAI } from "workers-ai-provider";
import { routeAgentRequest } from "agents";

export class MyAgent extends Think<Env> {
  getModel() {
    return createWorkersAI({ binding: this.env.AI })("@cf/moonshotai/kimi-k2.6");
  }
}

export default {
  async fetch(request: Request, env: Env) {
    return (await routeAgentRequest(request, env)) || new Response("Not found", { status: 404 });
  },
} satisfies ExportedHandler<Env>;

wrangler.jsonc:

{
  "compatibility_date": "2026-09-30",
  "compatibility_flags": ["nodejs_compat"],
  "ai": { "binding": "AI" },
  "durable_objects": { "bindings": [{ "class_name": "MyAgent", "name": "MyAgent" }] },
  "migrations": [{ "new_sqlite_classes": ["MyAgent"], "tag": "v1" }],
  "observability": { "traces": { "enabled": true } } // optional: traces in the Agents dashboard view
}

On the client, use useAgent({ agent: "MyAgent" }) with useAgentChat({ agent }) from @cloudflare/ai-chat/react. Then read the Think getting started guide and the assistant example.

D. AIChatAgent: when you want to own the model call

npm i @cloudflare/ai-chat agents ai @ai-sdk/react workers-ai-provider

import { AIChatAgent } from "@cloudflare/ai-chat";
import { createWorkersAI } from "workers-ai-provider";
import { streamText, convertToModelMessages } from "ai";

export class ChatAgent extends AIChatAgent {
  async onChatMessage(_onFinish, options) {
    const workersai = createWorkersAI({ binding: this.env.AI });
    const result = streamText({
      model: workersai("@cf/zai-org/glm-4.7-flash"),
      system: "You are a helpful assistant.",
      messages: await convertToModelMessages(this.messages),
      abortSignal: options?.abortSignal, // forward it, or cancelled calls keep running
    });
    return result.toUIMessageStreamResponse();
  }
}

The new_sqlite_classes migration is required, with the same wrangler shape as above and ChatAgent as the class name. Docs: Chat agents.

C. Agent class with a wakeup, for background agents

import { Agent } from "agents";

export class ReminderAgent extends Agent {
  async onRequest(request) {
    // run sendReminder in 30 seconds, survives hibernation
    await this.schedule(30, "sendReminder", { message: "Check your email" });
    // every day at 08:00 UTC
    await this.schedule("0 8 * * *", "dailyDigest", {});
    return new Response("Scheduled!");
  }
  async sendReminder(payload) { console.log(payload.message); }
  async dailyDigest() { /* build and send the digest */ }
}

Pass { idempotent: true } as the fourth argument when you call schedule() from onStart(), so restarts do not create duplicates. For long work use runFiber() with ctx.stash(). Docs: Schedule tasks, Durable execution, Quick start.

A. Plain Worker with the AI SDK

npm i ai workers-ai-provider

import { generateText } from "ai";
import { createWorkersAI } from "workers-ai-provider";

export default {
  async fetch(request: Request, env: Env) {
    const workersai = createWorkersAI({ binding: env.AI });
    const { text } = await generateText({
      model: workersai("@cf/zai-org/glm-4.7-flash"),
      prompt: "Summarise this ticket in two sentences: ...",
    });
    return Response.json({ text });
  },
};

This needs only "ai": { "binding": "AI" } in the Wrangler config. To use OpenAI or Anthropic, swap the provider package (@ai-sdk/openai). To route across providers with caching and limits, pass a gateway option when calling env.AI.run. Docs: Using AI models.

F. MCP server

npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless
npx @modelcontextprotocol/inspector@latest   # connect to http://localhost:8788/mcp
npx wrangler@latest deploy

That template still uses the deprecated McpAgent. For a new server, start from the mcp-worker example and createMcpHandler(). Add auth with Access or an OAuth provider. Full guide: Build a remote MCP server.

B. Workflow, and starting one from an agent

export class ProjectManager extends Agent {
  async startDeployment(task) {
    const instanceId = await this.runWorkflow("DEPLOY_WORKFLOW", {
      taskId: task.id, environment: "production",
    });
    // store instanceId in state, then go back to sleep
  }
  async onWorkflowComplete(workflowName, instanceId, result) {
    // the agent wakes up here when the workflow finishes
  }
}

The workflow class and its binding are not shown. Take them from Run Workflows. The snippet is from the long-running agents page. The Agents docs and the Workflows docs describe step limits differently. For step duration and CPU limits, check the Workflows limits page and verify the number you rely on.

6. Combinations, and traps to avoid

These combinations work:

Agent + Workflow: the agent owns its rhythm (reminders, polling, state) and a Workflow handles the heavy pipeline such as deploys. The docs use both in one project manager agent.
Think + MCP tools: Think agents can use tools from MCP servers. An MCP server you build (F) becomes a tool source for a Think agent (E).
Orchestrator + sub-agents: a parent Think or Agent delegates to children, each with its own storage.
Any agent + AI Gateway: route models across providers with caching and rate limits through the shared ai binding.
Code Mode: the model writes one piece of code that calls many tools, run in a sandbox. This helps when an API or MCP server has many tools.

Watch out for these:

Think is experimental, and the docs mark runTurn() as "Experimental: stable in shape, but may evolve before Think graduates out of experimental". Check its status before you promise a customer a production date.
If the path is known in advance, a Workflow is simpler and more predictable than an agent. The docs define agents as non-deterministic and workflows as linear and deterministic.
Variables in memory are lost. Only setState, this.sql, schedules and fiber checkpoints survive eviction.
For tools that reach a firewall or internal API, pair any option with Workers VPC (beta at the time of writing) or a Cloudflare Tunnel.

Sources

The other documentation pages are linked in the option cards above.

AI on Cloudflare: decision matrix

2026-10-07T00:00:00Z

The first matrix maps your situation to the Cloudflare building blocks you need. The second compares the options for building an agent: AIChatAgent, Project Think, an MCP server on a Worker, an existing harness, Cloudflare OS, VibeSDK and more.

How to read it

Core and included items give a working, safe setup.
Add recommended items when they apply, for example DLP if prompts hold personal data.
Optional items are for specific needs. Not needed items are not part of the situation.
Provided in the second matrix means the platform supplies it. You may still write code to use it.

1. Your situation: which building blocks do you need?

●Core Put it in place first.✓Included Built into the product.◐Recommended Add it when it applies to you.○Optional Only for specific needs.·Not needed Not part of this situation.

Your situation	Who	Models	Tools		Data and prompts			Run safely		Visibility		Other		Core
Your situation	Access and your IdP	AI Gateway	MCP server portal	Code Mode	DLP	AI Security for Apps	Secure Web Gateway	Sandbox or Dynamic Worker	Private network reach	Shadow IT and CASB	Logs to your SIEM	AI Crawl Control and Bots	Build on Workers and Agents SDK	Core
You build AI
A. AI in your productYour customers use AI that you built.	○	●	○	○	◐	●	·	○	○	·	◐	◐	○	2
B1. A workspace for all staffAgents, documents and small apps for non-developers. Cloudflare OS is a ready-made start.	●	✓	◐	✓	◐	·	○	✓	○	○	◐	·	·	4
B2. Governed agents for engineers and ITAgents with shell, repos and tests, under your rules.	●	●	●	◐	◐	·	○	●	●	○	●	·	◐	6
B3. Agents your teams already useClaude Code, opencode, Codex and similar. You secure them, you do not build a loop.	●	●	◐	○	◐	·	◐	○	○	◐	◐	·	·	2
B4. Your own agent for a processYou build it on Workers and the Agents SDK.	◐	●	◐	◐	◐	○	○	◐	◐	·	◐	·	●	2
You adopt AI
C. Your staff use third-party AIChatGPT, Claude, Gemini, coding assistants. Nothing to build.	◐	◐	○	·	●	·	●	·	·	●	◐	·	·	3
D. AI visits your sitesCrawlers and agents read your content. Pay per crawl is in private beta.	·	·	·	·	·	·	·	·	·	·	·	●	·	1

Situations against building blocks. Read across a row.

A. AI in your product

Your customers use AI that you built.

Core: put it in place first

AI Gateway: Put AI Gateway between your app and the model: logs, budgets, caching, fallback, guardrails.
AI Security for Apps: Detects prompt injection, PII and unsafe topics in requests to your AI endpoints. Needs the WAF.

Recommended: add it when it applies

DLP: DLP in AI Gateway scans prompts and responses for sensitive data.
Logs to your SIEM: Send AI Gateway logs to your SIEM with Logpush.
AI Crawl Control and Bots: Bots and rate limiting protect your AI endpoints. AI Crawl Control covers content scraping.

Optional: only for specific needs: Access and your IdP, MCP server portal, Code Mode, Sandbox or Dynamic Worker, Private network reach, Build on Workers and Agents SDK.

Not needed: Secure Web Gateway, Shadow IT and CASB.

B1. A workspace for all staff

Agents, documents and small apps for non-developers. Cloudflare OS is a ready-made start.

Core: put it in place first

Access and your IdP: Cloudflare Access controls who can enter. Inside, every agent and app starts with access to nothing.

Included: built into the product

AI Gateway: All inference runs through AI Gateway, attributed per person or team, with budgets and limits.
Code Mode: The agent works by writing and running code (Code Mode).
Sandbox or Dynamic Worker: Server code runs in a Dynamic Worker with outbound internet off. Client code runs in a sandboxed frame.

Recommended: add it when it applies

MCP server portal: Existing MCP servers connect through MCP server portals. Gatekeepers cover other systems.
DLP: Not described in the public Cloudflare OS sources. Plan it with your Zero Trust setup.
Logs to your SIEM: Send Access, Gateway and AI Gateway logs to your SIEM.

Optional: only for specific needs: Secure Web Gateway, Private network reach, Shadow IT and CASB.

Not needed: AI Security for Apps, AI Crawl Control and Bots, Build on Workers and Agents SDK.

B2. Governed agents for engineers and IT

Agents with shell, repos and tests, under your rules.

Core: put it in place first

Access and your IdP: People sign in with your IdP through Access. Optional device posture checks.
AI Gateway: Model calls go through AI Gateway behind Access. Provider keys stay in the gateway.
MCP server portal: Give each role its tools through an MCP server portal. Access logs each tool call.
Sandbox or Dynamic Worker: Run each session in a Sandbox or Container, removed on exit.
Private network reach: Mesh or Tunnel routes reach only what the user's group may reach.
Logs to your SIEM: Send logs to your SIEM as evidence of who reached what.

Recommended: add it when it applies

Code Mode: Code Mode helps when the tool set is large.
DLP: Scan prompts and responses.
Build on Workers and Agents SDK: Build the agent loop on Workers, or use an existing coding agent.

Optional: only for specific needs: Secure Web Gateway, Shadow IT and CASB.

Not needed: AI Security for Apps, AI Crawl Control and Bots.

B3. Agents your teams already use

Claude Code, opencode, Codex and similar. You secure these agents and do not build a loop.

Core: put it in place first

Access and your IdP: Put Access in front of the gateway domain and the portal.
AI Gateway: Route the agent's model calls through AI Gateway. The docs have guides for Claude Code, Claude Desktop, Gemini CLI, GitHub Copilot CLI, OpenAI Codex, OpenCode, Pi and VS Code.

Recommended: add it when it applies

MCP server portal: If the agent uses internal or SaaS tools, add the portal as its remote MCP server.
DLP: Scan prompts for sensitive data.
Secure Web Gateway: Gateway policies can block direct provider endpoints so calls cannot bypass the gateway.
Shadow IT and CASB: See which AI tools are used beyond the approved ones.
Logs to your SIEM: Send logs to your SIEM.

Optional: only for specific needs: Code Mode, Sandbox or Dynamic Worker, Private network reach.

Not needed: AI Security for Apps, AI Crawl Control and Bots, Build on Workers and Agents SDK.

B4. Your own agent for a process

You build it on Workers and the Agents SDK.

Core: put it in place first

AI Gateway: Send every model call through AI Gateway.
Build on Workers and Agents SDK: Choose Project Think, AIChatAgent, the Agent class, a Workflow or a plain Worker.

Recommended: add it when it applies

Access and your IdP: Put Access in front of your agent's chat page or portal.
MCP server portal: Expose your tools through a portal, or use tools that the portal offers.
Code Mode: For many tools or one large API.
DLP: Scan prompts and responses.
Sandbox or Dynamic Worker: If the agent runs code that it generates.
Private network reach: Tunnel, or Workers VPC (beta), if your tools sit on a private network.
Logs to your SIEM: Send logs to your SIEM.

Optional: only for specific needs: AI Security for Apps, Secure Web Gateway.

Not needed: Shadow IT and CASB, AI Crawl Control and Bots.

C. Your staff use third-party AI

ChatGPT, Claude, Gemini, coding assistants. Nothing to build.

Core: put it in place first

DLP: DLP profiles on prompts and uploads.
Secure Web Gateway: Gateway HTTP policies: allow, block, redirect, or limit actions inside AI apps. Needs the root certificate on devices.
Shadow IT and CASB: Shadow IT dashboard and API CASB. CASB has integrations for ChatGPT, Claude and Gemini.

Recommended: add it when it applies

Access and your IdP: Put the approved AI path behind Access.
AI Gateway: Offer an internal AI Gateway as the approved way to use models.
Logs to your SIEM: Send Gateway logs to your SIEM.

Optional: only for specific needs: MCP server portal.

Not needed: Code Mode, AI Security for Apps, Sandbox or Dynamic Worker, Private network reach, AI Crawl Control and Bots, Build on Workers and Agents SDK.

D. AI visits your sites

Crawlers and agents read your content. Pay per crawl is in private beta.

Core: put it in place first

AI Crawl Control and Bots: See which AI services access your content, allow or block each one, and check robots.txt compliance.

Not needed: Access and your IdP, AI Gateway, MCP server portal, Code Mode, DLP, AI Security for Apps, Secure Web Gateway, Sandbox or Dynamic Worker, Private network reach, Shadow IT and CASB, Logs to your SIEM, Build on Workers and Agents SDK.

Also decide: where the model runs

This applies to A and B1 to B4.

Workers AI runs models on Cloudflare with no API keys.
Hosted providers (OpenAI, Anthropic, Google) are reached through AI Gateway.
Private inference runs on machines you own. AI Gateway custom providers connect models that have an HTTPS API. Check the network path for your setup.

2. Building an agent: which option gives you what?

This applies to situation B (internal AI you build) and to AI in your product.

✓Provided The platform gives it to you.◐Partly Partly, or you or your tool add it.·Not provided Not part of this option.?Not stated Not stated in the public sources.

Option	Remembers state	Wakes itself up	Survives crashes and deploys	Chat with history and streaming	Runs the model loop	Exposes tools to other AI apps	What you write
Plain Worker with the AI SDKOne prompt in, one answer out.	·	·	·	·	◐	·	About 10 lines: the handler, prompt and tools.
Workflow with model stepsFixed steps with retries or approval.	◐	◐	✓	·	·	·	The step code, the workflow class and its config.
Agent class, your own harnessBackground agents: email, webhooks, cron.	✓	✓	✓	◐	·	·	The turn logic, prompts, tool calls and message format.
AIChatAgentA chat product where you own the model call.	✓	✓	✓	✓	◐	·	About 15 lines: streamText, tools, system prompt.
Project ThinkExperimentalA stateful chat agent, shipped fast.	✓	✓	✓	✓	✓	·	3 lines for a first agent: getModel().
MCP server on a WorkercreateMcpHandlerGiving other AI apps your tools.	·	·	·	·	·	✓	Tool definitions with good descriptions.
Existing harness, securedClaude Code, opencode, CodexGoverning agents your teams already use.	◐	·	·	◐	◐	·	Policy, not code: gateway, portal, DLP, Access.
Cloudflare OSEarly accessA workspace for all staff.	✓	✓	?	✓	✓	·	Configuration, Gatekeepers, skills and context.
VibeSDKReference implementationA platform where users build apps with an agent.	✓	?	?	✓	✓	·	Deployment and configuration: model providers, domain, templates.
Orchestrator with sub-agentsSpecialised roles or many long-lived contexts.	✓	✓	✓	◐	◐	·	The delegation logic. One class per role.

Agent options against capabilities.

"Not stated" means the public sources do not say. For the existing-harness row, the AI Gateway docs have guides for coding agents such as Claude Code, OpenAI Codex and OpenCode.

Plans and status

DLP and the AI detections in AI Security for Apps are paid add-ons on Enterprise plans.
Secure Web Gateway HTTP policies need the Cloudflare root certificate or a custom certificate on the device.
Code Mode and Project Think are experimental. Cloudflare OS is early access. VibeSDK is a reference implementation and builds on experimental and beta features. Dynamic Workers have been in open beta since March 2026.
Workers VPC is in beta and pay per crawl is in private beta.
Sandboxes need the Workers Paid plan.
New MCP servers use createMcpHandler. McpAgent is deprecated.

I checked this page against the Cloudflare documentation on 7 October 2026.

Sources

The Cloudflare documentation for each product is linked in the items above. Other sources are the Cloudflare OS launch post and the VibeSDK README.