CodeAct

CodeAct is an agent pattern in which the model acts by writing a block of executable code, usually Python, and the runtime runs the whole block as a single action. The usual contract has the model emit one structured tool call per turn and wait for the result. Xingyao Wang and colleagues named the pattern in a 2024 ICML paper. The agent still loops, observes, and corrects like any ReAct-style agent; what changes is the unit of action. One generated program can call five tools, branch on intermediate results, retry failures, and return only the final answer, where a JSON-calling agent would need five model round trips to do the same work.

Code as the action space#

A conventional tool-calling agent has a fixed menu: the tools you defined, called one at a time, with arguments shaped by a JSON schema. CodeAct replaces that menu with a programming language. Tools become functions the generated code can call, and the model also gets everything the language already has: variables to hold intermediate results, loops to repeat work, conditionals to branch, libraries like pandas to process data that never needs to enter the model's context.

The original paper tested this across 17 LLMs and found code actions outperformed JSON and text action formats by up to 20% in success rate on a benchmark of tasks that need several tools. The likely reason is that models have seen far more real Python in training than your own JSON format, and code says "do A, feed it to B, then C" in one action. The team also released CodeActAgent, a model fine-tuned to act this way, and OpenHands (formerly OpenDevin) named its default agent CodeActAgent after the pattern.

Why one code block beats many round trips#

Count the costs of a chained task under each contract. Say the job is "compute Q3 net revenue and file a report": fetch orders, fetch refunds, subtract, write the report. With JSON tool calls that is three or four model round trips, each one a full inference pass costing seconds of latency, and every raw result, potentially thousands of rows, gets pasted into the context so the model can decide the next step. With CodeAct the model writes one script: two fetches into variables, a subtraction, one report call. One inference pass, and the row data never touches the context.

Three things come with the language once the action is a program. Chaining tools is passing a variable, with no extra turn. A loop such as "check budget compliance for 20 employees" runs as one action instead of 20 round trips, and Anthropic's docs use that example for programmatic tool calling. Errors can be caught in the code, retried with a pause between attempts, or routed to a second data source without calling the model again. When the code does fail, the interpreter's traceback tells the model far more than "tool returned error", and the CodeAct paper reports that its agent could debug itself from those messages.

The context savings are where production teams feel it. Anthropic's "code execution with MCP" post takes one example, copying a meeting transcript from Google Drive into a Salesforce record, from 150,000 tokens of tool definitions and intermediate results down to 2,000 tokens, a 98.7% reduction, by letting the agent import MCP servers as code and keep the transcript in the execution environment. Treat that as the best case for one workflow. The measured numbers in Anthropic's programmatic tool calling docs are smaller: on agentic search benchmarks it raised performance by an average of 11 percent while using 24 percent fewer input tokens. The same docs report the other side. On a benchmark where each turn makes one or two sequential tool calls, turning it on left scores unchanged and cost about 8 percent more, because a script cannot skip the model's turn when every call depends on reasoning over the last result. Measure billed input tokens with and without code actions on a sample of your own traffic before you turn them on everywhere.

The sandbox is a hard requirement#

A JSON tool call can only do what the tool allows. Generated code can do anything the interpreter can, which is the point of the pattern and its risk. Run model-written code with real permissions and a single bad step can delete files or send an environment variable somewhere it should not go, and prompt injection lets text the model reads write that step for an attacker.

Decide where the code runs before you decide anything else about the agent. Give each session its own isolated runtime. A plain Docker container shares the host's kernel, so for code nobody reviewed, choose gVisor, which intercepts the container's system calls, or a Firecracker microVM, a small virtual machine with its own kernel. Put no credentials inside beyond scoped tokens for the tools you mean to expose, allow outbound network traffic only to your own APIs, and cap CPU, memory and wall-clock time so a runaway loop is killed. Hosted sandboxes such as Anthropic's code execution tool, E2B and Modal exist so teams do not have to build that isolation themselves. Smolagents, Hugging Face's agent library, says plainly that its built-in local Python executor is not a security boundary, which holds for any interpreter running in your own process.

Where it shows up, as of October 2026#

Open Interpreter (2023) put the "model writes code, your machine runs it" loop on developer laptops before the pattern had a name. The CodeAct paper (February 2024) formalized it, and Smolagents made code-writing agents its first-class agent type, with a tool-calling agent offered alongside.

Providers then built it in. Anthropic's code execution tool reuses containers across requests, and its programmatic tool calling, generally available from the code_execution_20260120 tool version, turns your declared tools into functions the sandboxed code can call directly. OpenAI's code interpreter and Google's Gemini code execution cover the same ground. Anthropic's November 2025 post went furthest, presenting whole MCP servers as code modules on a filesystem so the agent reads only the tool definitions it needs. If you are on one of these APIs, try the provider's version before you build your own interpreter loop, because it ships with the isolation already done.

Code for reading data, typed tools for changing systems#

The crossover is chaining. With one or two independent calls per turn, stay with JSON tool calls: code adds tokens and an interpreter hop for no gain, a schema checks each call, and the log holds one typed action per line. Pipelines, the same call run across a list, and large intermediate results the model only needs in aggregate are where a code action wins on tokens and latency at once.

We split it by what the action does. On the executive operations agent we built, spreadsheet work runs as code: the agent infers the schema, writes code, runs it, inspects the result and refines, and it hands back a notebook that re-runs. A reviewer checks the notebook instead of trusting a paragraph about the numbers, and spreadsheet analysis that took hours came down to under 15 minutes. On the DevOps agent that changes live AWS accounts, we did the opposite. It reaches AWS only through purpose-built tools for account reads, template generation, validation, rendering and a controlled apply, with no general shell and no path from a plan step to an arbitrary API call, so every step is either machine-checkable or reviewable by an engineer.

Use code where the action reads and computes, and typed tools where it changes something a person has to approve. A human who reviews every write can approve one discrete call. A 40-line script that mixes reads and writes is much harder to approve, and plan-and-execute systems that show a step list before anything runs need the discrete version for the same reason.