Code execution tool

Also known as: code interpreter tool

On this page 8

A code execution tool is a capability that lets a language model write a program, run it in an isolated environment and read back the actual output, errors and generated files. In the field of AI agents, it is one of the most widely used tools, because it replaces guessed answers with computed results for arithmetic, data analysis, file conversion and testing.

The tool is also known as a code interpreter tool, after the early products that popularized it. Unlike an ordinary function call with a fixed schema, a code execution tool accepts arbitrary code as its argument, which makes it extremely flexible and, for the same reason, a component that demands strict sandboxing and permission control.

How a code execution tool works inside the agent loop

A code execution tool works as a round trip between the model and a sandbox. The model emits a tool call whose payload is source code, most often Python, the runtime executes it, and the captured standard output, error trace and file list are returned to the model as the next observation.

  1. The model decides that a step needs computation rather than recall.
  2. It produces a tool call containing code and, optionally, a language identifier.
  3. The host passes the code to an isolated execution environment.
  4. The sandbox runs the code under time, memory and network limits.
  5. Output, exceptions and new files return to the model as a tool result.
  6. The model interprets the result, fixes errors or continues the task.

This cycle is a specialized form of the agent loop. Because errors come back as text, the model can read a traceback and repair its own code, often within two or three iterations, which is the main reason the tool raises reliability on quantitative tasks.

Core components and their parameters

Every code execution tool combines a runtime, an isolation layer and a set of resource limits. The table below summarizes the parameters that operators configure most often and the typical ranges seen in practice.

ParameterCommon settingWhat it controls
Language runtimePython 3 with data librariesWhich code the model can run
Execution timeoutAbout 30 seconds to several minutesHow long one call may run
Memory limitHundreds of megabytes to a few gigabytesSize of data the code can load
Network accessDisabled or limited to an allowlistExposure to data exfiltration
File systemTemporary working directoryWhere uploads and outputs live
Session stateStateful kernel or fresh processWhether variables persist between calls
Typical configuration of a code execution sandbox

Stateful sessions keep variables and loaded files between calls, much like a notebook kernel, which saves time in multi-step analysis. Stateless execution starts a clean process every time, which is simpler to secure and to reproduce but forces the model to reload data on each call.

Isolation models for running untrusted code

Code written by a model must be treated as untrusted code, because it can contain mistakes or instructions planted through prompt injection. The isolation technology decides how much damage a bad program could cause, and the following table compares the common options.

Isolation optionStrength of isolationStartup cost
Language-level sandboxWeak, easy to escapeVery low
ContainerModerate, shares the host kernelLow
Hardened container runtimeStrong, intercepts system callsLow to moderate
MicroVMStrong, separate guest kernelModerate, often under one second
WebAssembly runtimeStrong, capability-basedVery low, limited library support
Isolation options compared

Production systems usually combine a microVM or hardened container with disabled network access and short-lived environments. This topic overlaps with the broader agent sandbox concept, which also covers browsers and shells, whereas the code execution tool is the specific interface the model calls.

Code execution compared with other agent tools

A code execution tool differs from other tools by how much freedom it hands to the model. A typed function exposed through tool calling or an MCP server performs one predefined action, while code execution lets the model compose any action the runtime permits.

CapabilityModel inputMain risk
Typed function callArguments matching a tool schemaMisuse of one specific action
Code execution toolArbitrary program textUnbounded actions inside the sandbox
Shell accessOperating system commandsChanges to files, packages and processes
Computer-use agentMouse and keyboard actionsUnintended clicks in real applications
Code execution and neighboring capabilities

In coding agents, the boundary blurs: a coding agent may run tests through a shell in a full repository, while a code interpreter typically works in a disposable scratch environment focused on calculation and data handling.

When to enable code execution

Code execution is worth enabling whenever a task needs exact computation, structured data processing or verifiable output. It adds latency and infrastructure cost, so it should not be the default for purely conversational assistants.

TaskRecommended choiceReason
Statistics on an uploaded fileEnable code executionResults are computed, not estimated
Chart or report generationEnable with file outputLibraries produce exact graphics
Simple factual questionLeave it disabledNo computation adds value
Access to a business systemUse a typed tool insteadNarrower permissions are safer
Decision guide for code execution

Risks and common mistakes

Most incidents involving a code execution tool come from weak isolation or excessive permissions, not from the model’s intent. A document that contains hidden instructions can steer the model into writing code that reads secrets or sends data elsewhere.

  • Leaving network access open allows exfiltration of uploaded files or credentials.
  • Mounting real credentials into the sandbox turns a code bug into a security incident.
  • Reusing one environment across users can leak data between sessions.
  • Trusting output without inspection: code can run successfully and still compute the wrong thing.
  • Missing resource limits let infinite loops or huge allocations stall the service.

The short version

A code execution tool gives an AI assistant a private calculator that can run whole programs. When a question involves numbers, spreadsheets or charts, the assistant writes a small program, runs it in a locked room and looks at the real result instead of guessing.

The locked room matters. The program cannot touch the rest of the computer or the internet unless someone allows it, so mistakes stay contained while the answers become far more reliable.

Where it makes a difference

A regional retail analyst uploads a CSV export with about 250,000 sales rows and asks an AI agent for monthly revenue by store, the five weakest product categories and a trend chart. Without code execution, the model could only estimate figures from a sample of the text it can read.

With the tool enabled, the agent writes a pandas script, runs it in a microVM with no network access and a two-minute timeout, and receives the aggregated table. A first attempt fails because one date column uses a different format; the agent reads the traceback, adds a parsing rule and reruns the script successfully.

The analyst receives exact totals, a downloadable chart and the script itself, which a colleague can rerun to verify the numbers. The uploaded file is deleted when the session ends, so no sales data remains in the environment.