Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/cloudflare-os/llms.txt

Use this file to discover all available pages before exploring further.

The Cloudflare OS agent is a fully general-purpose AI assistant. While it excels at building Gadgets, you can use it for any task — writing, analysis, research, automation — without creating an app at all. What makes it distinctive is how it performs those tasks: the Cloudflare OS agent is a Code Mode agent, meaning it acts by writing and immediately executing snippets of code rather than by calling a fixed set of predefined tools.
To get a feel for what the agent can do, try prompts like:
  • “Make slides for my upcoming meeting with a customer.” (Uses the built-in Slides Blueprint.)
  • “Make a collaborative whiteboard app.” (Builds a new Gadget from scratch.)
  • “Make an issue dashboard for this GitHub repo.” (Requires the GitHub Gatekeeper.)
  • “Fix the typos in this Google Doc.” (Requires the Google Gatekeeper.)

​
Code Mode explained

In most agent frameworks, tools are defined upfront as a fixed list of functions. The agent picks from the list, fills in parameters, and calls the tool. This works, but it creates a rigid interface between the agent and the world. Cloudflare OS agents use Code Mode instead. When the agent wants to accomplish a step in a task, it writes a JavaScript snippet and executes it. The snippet can call any method on any resource that has been introduced to the session — Gatekeeper APIs, Gadget methods, spawner controls — all via natural code. 
// Example: agent writes and executes a snippet to read a GitHub issue
const issue = await env.MY_REPO.getIssue(42);
const body = issue.body;
// ... continues processing
This approach is a win on two dimensions:
  1. Low boilerplate for the agent. Cap’n Web RPC means the agent calls service methods as if they were local function calls, with no HTTP wrangling or JSON parsing.
  2. Any API is automatically a tool. The Gadget’s own server methods, Gatekeeper APIs, and spawner controls are all directly callable from executeCode. There is no need to build a separate tool layer.

​
Context and the Context Library

Before the agent begins a task, it reads from the Context Library — an auto-provisioned Gatekeeper that provides named collections of context documents. These documents are surfaced to the agent as observations (read-only inputs) at the start of each chat session. Context collections come in two forms:
TypeCreated byReadable by
PublicDeployment adminsAll users automatically
PrivateIndividual usersThat user only
Admins use the Context Library to give the agent knowledge about how the company operates — org charts, runbooks, coding standards, product context. Users can create their own private collections for personal context. The agent reads these automatically via getSession() and getAgentCatalog() on the context account; each read is recorded as an observation in the action log. Because the Context Library is auto-provisioned, there is no OAuth flow and no introduction step. It is always available in the agent’s environment.

​
Capability-based tool access

A freshly opened agent session has access to nothing external. Even if you have configured a dozen Gatekeeper accounts, the agent cannot use any of them until you explicitly introduce a resource to the session. Introductions happen in three ways:
  • Paste a link to a resource (e.g., a GitHub repo URL or Google Doc URL). The Workshop creates a Gatekeeper for that resource and surfaces it as a named binding in the chat’s environment.
  • Use the “Add resource” UI to select a resource from a connected account via the resource configurator.
  • The agent requests a connection. The agent emits a connectionRequest chat message naming the vendor, resource type, and reason. You accept or deny it inline; on acceptance the Gatekeeper is created and the agent is resumed.
Once introduced, the resource appears in the agent’s executeCode environment as env.BINDING_NAME, where the binding name is a JavaScript identifier the agent chooses when making the request.

​
Gatekeeper bindings in executeCode

When the agent’s code snippet runs, it receives an env object populated with every resource introduced to the current chat. Two methods on the agent session are important for understanding what is available:
  • getSession() — returns the agent’s own session stub, including references to the chat’s bound Gatekeepers and ambient singletons (Context Library, Scheduler).
  • getAgentCatalog() — returns a description of the Gatekeeper APIs available in the current session, formatted as text for the agent’s context window.
The agent reads getAgentCatalog() at the start of each turn to understand what it can call, then writes executeCode snippets that call those methods directly.

​
Agent spawners

A Gadget can define agent spawner bindings — configuration that allows the Gadget’s server code to programmatically create new agent chat threads at runtime. This is how Gadgets implement automated workflows: a Gadget that processes incoming emails might spawn a separate agent for each message. Each spawner binding is created with an AgentSpawnerConfig: 
{
  displayName: "Email Responder",
  modelId: "claude-sonnet-5",       // model to run, or null for human-only chats
  env: {
    MAILBOX: 14,                     // workpiece ID of the mailbox Gatekeeper
  }
}
The env field defines exactly which resources the spawned agent can access — a snapshot taken at spawn time. The spawned agent sees only these bindings, never the workspace’s full default binding list. This is the right security primitive for preventing prompt injection between email threads or other isolated task contexts. Spawner bindings are configured from the Connections panel and appear as a binding type in Blueprints so that Blueprint consumers can choose which model their spawner should use.

​
Model providers

Cloudflare OS works with all major AI model providers. Models are configured per-user from the Settings panel and identified by a stable string ID used throughout the API.
ProviderExample models
AnthropicClaude Opus 5, Claude Sonnet 5, Claude Haiku 4.5
OpenAIGPT 5.6 Sol, GPT 5.6 Luna, GPT 5.6 Terra
GoogleGemini 3.6 Flash
Cloudflare Workers AIKimi K2.7 Code, GLM 5.2
OllamaAny self-hosted model
Each model is configured with a provider, model name, and API token. Cloudflare Workers AI models also require an account ID. You can point any provider at a custom API URL (e.g., Cloudflare AI Gateway) by setting the apiUrl field.
Bring Your Own Key (BYOK): AI model usage is billed to the API token attached to the model configuration of the user who sent the message — not the Gadget owner. When a collaborator uses the agent inside a shared Gadget, their model configuration and API token are used for that turn. This means Gadget owners are not charged for their collaborators’ AI usage.

​
Compaction

Long agent conversations eventually approach the model’s context window limit. When this happens, the Workshop performs compaction: a background step that summarizes earlier portions of the conversation history and replaces them with a compact checkpoint. Compaction is transparent to the user — the full message history remains readable in the UI, but older messages are replaced by a summary in the model’s prompt for subsequent turns. The AiChatMetadata.compactedTo field records the sequence number through which the current compaction checkpoint covers, so the client can page through history one checkpoint-delimited segment at a time. The outputLimit field on each model configuration (used for Workers AI models with a fixed response budget) is how the Workshop sizes the prompt budget for compaction — reserving outputLimit tokens for the response and targeting the remainder as the maximum prompt size.

Build docs developers (and LLMs) love

Get started for freeTalk to us