Tools become
a program.

There is still an agent loop.

Code Mode changes the action inside the loop. The host exposes a tool with an input like { code: string }. The model puts JavaScript in that string. A sandbox runs it, calls back to approved host capabilities, and returns a result or error. The model can then answer or write another program.

This is a change in where orchestration happens. JSON can carry a whole workflow too—if a host implements such a workflow tool. The comparison here is against individual tool calls.

The current package has two layers

The first is enough to understand the core idea. The second is important to understanding the current package. Do not read an older quick start and assume it describes every feature—or that the simple helper automatically includes the durable runtime.

createCodeTool · tool.ts:89 · runtime handle · runtime-handle.ts:90

Let the program carry the intermediate data.

Suppose you want bug-fix pull requests whose checks pass. Our toy repository has three PRs: #17 “Fix timeout” (bug), #18 “Update docs” (docs), and #19 “Fix retry” (bug). Checks pass for #17 and fail for #19.

async () => {
  const prs = await codemode.listPRs({});
  const ready = [];
  for (const pr of prs) {
    if (!pr.labels.includes("bug")) continue;
    const check = await codemode.getChecks({ number: pr.number });
    if (check.pass) ready.push({ number: pr.number, title: pr.title });
  }
  return ready;
}

There are still three real tool calls: one list and two check queries. But one model-written action can compose them. The raw list and check objects need not all enter the next model prompt. The program returns [{ number: 17, title: "Fix timeout" }].

The saving is in model round trips and exposed intermediate data. It is not a promise of fewer API calls, correct filtering, or lower cost for every task. Printing the full response in a loop can fill the context again. A bad loop can also multiply writes.

ToolDispatcher · executor.ts:230 · proxy + Worker loading · executor.ts:467

Follow one action across the boundary.

A. Start with the small, one-shot helper

The developer supplies real functions. createCodeTool generates type declarations, places them in the tool description, and extracts the callable implementations. The model sees the declarations; the executor receives the implementations through host-side dispatch.

import { createCodeTool } from "@cloudflare/codemode/ai";
import { DynamicWorkerExecutor } from "@cloudflare/codemode";

// Host-side: myTools contains your AI SDK tools and execute functions.
const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
const codeTool = createCodeTool({ tools: myTools, executor });

// Pass this to your existing AI SDK model loop:
const modelTools = { codemode: codeTool };

The Workers executor needs a worker_loaders binding named LOADER. This is platform-specific execution infrastructure. Installing the npm package in a plain Node process does not give Node the Worker Loader API.

{
  "worker_loaders": [{ "binding": "LOADER" }],
  "compatibility_flags": ["nodejs_compat"]
}

The implementation then follows four steps:

1. Prepare. createCodeTool filters tools, generates declarations and wraps host functions. In the AI SDK adapter, available schema validators check inputs.
2. Normalize. normalizeCode removes code fences and wraps common forms into a callable function. Acorn parses JavaScript for this transformation. It is neither a security analysis nor a TypeScript compiler.
3. Execute. DynamicWorkerExecutor constructs a Worker module and loads a fresh sandbox. Generated Proxy objects route method calls back to the host with Workers RPC.
4. Observe. The return value and captured console logs come back. On this helper path, runCode throws if execution returns an error. The surrounding agent framework decides how to present that failure to the model.

schema extraction + wrapper · tool.ts:25 · normalizeCode · normalize.ts:1 · runCode · run-code.ts:1

B. Add connectors when you need discovery and durability

A connector maps an integration to a JavaScript namespace: github.list_pull_requests(…), for example. McpConnector wraps an existing MCP connection; OpenApiConnector derives methods from an API specification; custom connectors expose your own operations.

import {
  createCodemodeRuntime,
  DynamicWorkerExecutor,
  truncateResult
} from "@cloudflare/codemode";

// Inside an Agent / Durable Object; github is your configured connector.
const runtime = createCodemodeRuntime({
  ctx: this.ctx,
  executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
  connectors: [github],
  transformResult: (value) => truncateResult(value)
});
const modelTools = { codemode: runtime.tool() };

// Host-side approval handler, after authenticated user authorization:
// await runtime.approve({ executionId });

The runtime is a Durable Object facet: a named stateful component attached to the agent, with its own SQLite-backed execution history. The Worker entry must export CodemodeRuntime; the @cloudflare/codemode/vite plugin can add that export. The executor runs code once. The facet keeps what happened between runs.

createCodemodeRuntime · runtime-handle.ts:131 · facet lookup · proxy-tool.ts:910

Instead of dumping every method’s schema into the prompt, the runtime exposes a small discovery SDK and the configured namespace names. The model can first run:

async () => {
  const matches = await codemode.search("list pull requests");
  const docs = await codemode.describe(matches.results[0].path);
  return docs;
}

The running program is not another LLM. A string containing new documentation does not magically change code already generated. Returning relevant docs lets the next model turn use the discovered method. If the code can inspect a result mechanically, it need not return the whole object.

The search is weighted lexical matching over method paths, names and descriptions, plus saved snippets. It is not an embedding search. The four platform methods are search, describe, step and run. Connector methods perform the actual application work.

lexical scoring · connectors/search.ts:11 · model-facing instructions · proxy-tool.ts:553

C. Approval restarts the program, then replays completed calls

Consider a connector with list_items and create_item. The developer marks create_item as requiresApproval: true. Each call crosses the runtime, which decides: return an old result, execute now, or pause.

async () => {
  const before = await items.list_items();
  const created = await items.create_item({ title: "Investigate timeout" });
  return { beforeCount: before.length, created };
}

On the first pass, list_items executes and its result is logged. create_item becomes pending; the run aborts with a paused outcome. The host shows the pending arguments to an authorized user.

After approval, the same source code runs from the beginning in a fresh execution. The earlier list call returns its recorded result. The approved create runs, gets logged, and the code continues. No JavaScript stack or local variable snapshot waits in memory for hours. Variables are reconstructed by replay.

decide · runtime.ts:411 · connector dispatch · proxy-tool.ts:398 · approval + replay tests · runtime.test.ts:121

D. Replay has a contract

• Same calls, same order, same arguments. Changing a timestamp in a pending action’s arguments causes replay divergence. Wrap nondeterministic work in codemode.step("stamp", () => Date.now()) to record and replay the value.
• Sequence approval-capable calls. Prefer sequential await over Promise.all when a run may pause. Call sequence numbers are assigned by arrival at the host; racing arrivals can diverge on replay.
• Await effects before returning. Release of a sandbox is not cancellation of host work. The 0.5.5 patch releases pending RPC calls so they no longer retain Worker concurrency slots; already-started host calls may still take effect.
• A replayed read can be stale. That preserves control flow across approval. An explicit replay: "reexecute" read opts out of result storage and can return fresh data; it can also change later branches and trigger divergence. Revalidate authorization and business conditions on the host at write time.
• Reject is not undo. Rejecting ends a paused run. Rollback separately attempts developer-supplied revert functions in reverse order. Unrevertible actions remain; compensation can fail.

replay contract · docs/codemode/runtime.md · late-call gate · executor.ts:161 · rollback · proxy-tool.ts:1090

E. Keep the scope of each guarantee visible

executor configuration · executor.ts:263 · connector executeTool · base.ts:185 · model output projection · proxy-tool.ts:789 · snippet curation · docs/codemode/snippets.md

Security design detail: OpenApiConnector also exposes a low-level authenticated request escape hatch. Protecting a named write method is insufficient if an unrestricted alternative can perform the same write. Scope every route to the integration, including escape hatches.

OpenAPI escape hatch · openapi.ts:78

Can you predict the next step?

Five questions. Choose an answer to see why each option is right or wrong. You can change your answer. Everything runs locally in this page; no answers are submitted.

0 / 5 answered

Continue below for the research comparison and the original paper’s evidence.

CodeAct asks a broader research question.

Executable Code Actions Elicit Better LLM Agents is Xingyao Wang and colleagues’ ICML 2024 paper. It proposes executable Python as an agent action space: generate code, run it, observe results or errors, then revise through further turns. The paper also introduces a benchmark, interaction training data and fine-tuned models.

The common idea is clear. A model can express “fetch these records, loop, branch, compute” as a program. Tool outputs become variables instead of forcing every intermediate decision back through model text.

What CodeAct actually measured

The paper evaluates 17 LLMs on atomic API-Bank calls and 82 human-curated M³ToolEval tasks. The latter permits up to ten interaction turns and compares code actions with the tested JSON/text formats.

That is 20.7 percentage points over the next-best format for this model and task suite. Code wins or ties for best success on 12 of 17 models, not every model. On atomic API-Bank calls, GPT-4’s tested JSON formats do better than code. The fine-tuned Mistral CodeActAgent reaches 12.2% on M³ToolEval; the Llama-2 variant remains at 0%. The action format helps capable models express more, but does not replace capability.

These are 2024 model/benchmark results. They do not measure Cloudflare’s package, current models, sandbox strength, cost per successful production task or long-running reliability. Cloudflare’s “models are better at code” motivation is consistent with part of this evidence; it is not a universal theorem about every tool API.

How to keep the two ideas straight

If you already have a tool-using agent and want it to compose API work inside a restricted execution environment, Code Mode provides implementation pieces. If you want to study which action representation makes an agent more effective, CodeAct provides the research framing and experiments.

You could combine that research pattern with a Code Mode-style runtime: let the model write programs and self-correct, while the host enforces capabilities and durable approval. This is a design combination, not a claim that Cloudflare implements CodeActAgent or derives its code from that project. No direct code lineage was established in this check.

The model writes the plan in an executable language.
The host still owns the permission to carry it out.

Primary paper: Xingyao Wang, Yangyi Chen, Lifan Yuan, Yizhe Zhang, Yunzhu Li, Hao Peng and Heng Ji. CodeAct v4 PDF, §§2–3, Table 3, Figure 3 and Impact Statement. Original code, data and models. Cloudflare source, tests and verification scope are linked in the implementation record.