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.
- The model decides that a step needs computation rather than recall.
- It produces a tool call containing code and, optionally, a language identifier.
- The host passes the code to an isolated execution environment.
- The sandbox runs the code under time, memory and network limits.
- Output, exceptions and new files return to the model as a tool result.
- 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.
| Parameter | Common setting | What it controls |
|---|---|---|
| Language runtime | Python 3 with data libraries | Which code the model can run |
| Execution timeout | About 30 seconds to several minutes | How long one call may run |
| Memory limit | Hundreds of megabytes to a few gigabytes | Size of data the code can load |
| Network access | Disabled or limited to an allowlist | Exposure to data exfiltration |
| File system | Temporary working directory | Where uploads and outputs live |
| Session state | Stateful kernel or fresh process | Whether variables persist between calls |
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 option | Strength of isolation | Startup cost |
|---|---|---|
| Language-level sandbox | Weak, easy to escape | Very low |
| Container | Moderate, shares the host kernel | Low |
| Hardened container runtime | Strong, intercepts system calls | Low to moderate |
| MicroVM | Strong, separate guest kernel | Moderate, often under one second |
| WebAssembly runtime | Strong, capability-based | Very low, limited library support |
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.
| Capability | Model input | Main risk |
|---|---|---|
| Typed function call | Arguments matching a tool schema | Misuse of one specific action |
| Code execution tool | Arbitrary program text | Unbounded actions inside the sandbox |
| Shell access | Operating system commands | Changes to files, packages and processes |
| Computer-use agent | Mouse and keyboard actions | Unintended clicks in real applications |
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.
| Task | Recommended choice | Reason |
|---|---|---|
| Statistics on an uploaded file | Enable code execution | Results are computed, not estimated |
| Chart or report generation | Enable with file output | Libraries produce exact graphics |
| Simple factual question | Leave it disabled | No computation adds value |
| Access to a business system | Use a typed tool instead | Narrower permissions are safer |
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.