Skip to main content

Layer 2: Agent primitives

What makes it an agent and not a completion call: memory, models, search, a browser, a computer.

In this layer: Durable Objects, Workers AI, AI Search, Browser Run, Sandbox SDK, Containers.

Durable Objects​

What it is: One stateful instance per key (per device, per market, per case), with its own SQLite.

Use it when: Keeping state per device fingerprint, per market page or per incident across many requests.

// Every Agent IS a Durable Object. Raw access, one instance per key:
const stub = env.MY_AGENT.get(env.MY_AGENT.idFromName('device-ja4-abc'));
await stub.recordSignal({ path: "/login", at: Date.now() });

Basics: Durable Objects

Advanced: SQLite storage

Workers AI​

What it is: Open models on Cloudflare GPUs, one binding, no API key.

Use it when: Every model call today. Route it through your AI Gateway (Shield 1).

// wrangler.jsonc: "ai": { "binding": "AI" }
const out = await env.AI.run(
  '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
  { messages: [{ role: 'user', content: q }] },
  { gateway: { id: env.AI_GATEWAY_ID } },
);

Basics: Workers AI · Models

Advanced: Workers AI through AI Gateway

What it is: Managed retrieval: upload docs, get scored, citable chunks back. No vector DB to run.

Use it when: A portal helpdesk grounded in internal docs, or an agent that cites the runbook it used.

// wrangler.jsonc: "ai_search_namespaces": [{ "binding": "AI_SEARCH", "namespace": "default", "remote": true }]
const res = await env.AI_SEARCH.get('agent-docs').search({
  messages: [{ role: 'user', content: q }],
});
// res.chunks[].text, .item.key, .score

Basics: AI Search · Workers binding

Advanced: AI Search as an agent tool

Browser Run​

What it is: Headless Chrome on the network (formerly Browser Rendering): screenshot, markdown, scrape in one call.

Use it when: Verifying a product page after a release, or seeing your site the way an AI shopping agent does.

// wrangler.jsonc: "browser": { "binding": "BROWSER", "remote": true }
// quickAction returns a Response: read it before you use or store it
const { result: md } = await (await env.BROWSER.quickAction('markdown', { url: 'https://example.com/' })).json(); // body: { success, result }
const png = await (await env.BROWSER.quickAction('screenshot', { url })).arrayBuffer();

Basics: Quick actions

Advanced: Browser tools for agents

Sandbox SDK​

What it is: An isolated Linux box per agent: exec commands, write files, run code the model wrote.

Use it when: Running terraform plan on a proposed rule change before a human approves it.

import { getSandbox } from '@cloudflare/sandbox';
export { Sandbox } from '@cloudflare/sandbox';

const box = getSandbox(env.Sandbox, 'agent');
const plan = await box.exec('terraform plan -no-color');

Basics: Sandbox SDK · Get started

Advanced: Sandbox as an agent tool

Containers​

What it is: Run any image next to your Worker, addressed like a Durable Object.

Use it when: You need a binary or runtime that does not fit in a Worker. Heavy for a 70-minute build.

Basics: Containers

Advanced: Get started