# What Built-in Tools Are Available in Agent Zero for Executing Code: The `code_execution_tool` Deep Dive

> Explore Agent Zero's `code_execution_tool`, a powerful built-in for Python, Node.js & shell execution. Learn how it streamlines your coding tasks with persistent sessions.

- Repository: [Agent Zero/agent-zero](https://github.com/agent0ai/agent-zero)
- Tags: deep-dive
- Published: 2026-02-23

---

**Agent Zero provides a single built-in tool called `code_execution_tool` that supports Python, Node.js, and shell execution with persistent session management.**

The `agent0ai/agent-zero` framework ships with a versatile code execution engine designed to let agents run arbitrary code across multiple runtimes without requiring external tool configuration. This built-in capability is automatically available to every agent instance and handles everything from simple Python scripts to long-running interactive shell sessions.

## The `code_execution_tool`: Core Architecture and Implementation

### Source Location and Class Structure

The built-in code execution functionality is implemented by the **`CodeExecution`** class located in [`python/tools/code_execution_tool.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/code_execution_tool.py). This module defines the tool's interface, runtime handlers, and session lifecycle management. According to the framework's architecture documentation, this tool is listed among the core built-in tools that ship with Agent Zero, ensuring it is automatically included in every agent's system prompt via the template defined in [`prompts/agent.system.tool.code_exe.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.tool.code_exe.md).

### Supported Runtimes and Execution Modes

The `code_execution_tool` supports five distinct runtime modes, each designed for specific execution contexts:

- **`runtime: "python"`** — Wraps code strings in `ipython -c …` commands and executes them within an interactive Python REPL inside the container.
- **`runtime: "nodejs"`** — Passes JavaScript code to a helper script at [`/exe/node_eval.js`](https://github.com/agent0ai/agent-zero/blob/main//exe/node_eval.js) and executes it with the `node` binary.
- **`runtime: "terminal"`** — Executes raw commands in a persistent Bash session (or PowerShell on Windows hosts).
- **`runtime: "output"`** — Retrieves buffered `stdout`/`stderr` from a previously started terminal session without executing new code.
- **`runtime: "reset"`** — Terminates the selected session (or all sessions) and discards their state, effectively clearing the environment.

## How to Use Agent Zero's Built-in Code Execution Tool

### Executing Python Code

To run Python code, invoke the tool with `runtime` set to `"python"`. The framework automatically handles the IPython wrapper and container isolation:

```json
{
  "tool_name": "code_execution_tool",
  "args": {
    "runtime": "python",
    "code": "print('Hello from Agent Zero')"
  }
}

```

The agent receives the Python REPL output as a standard response string, allowing it to process results or chain subsequent logic.

### Running Persistent Shell Sessions

For multi-step terminal workflows, use the `session` parameter (defaulting to `0`) to maintain state across separate tool calls. Set `allow_running` to `false` to prevent accidentally overwriting active sessions:

```json
{
  "tool_name": "code_execution_tool",
  "args": {
    "runtime": "terminal",
    "code": "ls -la /a0/usr/projects",
    "session": 1,
    "allow_running": false
  }
}

```

This executes the command in session `1` and keeps the shell alive for future interactions.

### Retrieving Output and Managing Session Lifecycle

To fetch buffered output from a long-running terminal session without blocking, use the `output` runtime:

```json
{
  "tool_name": "code_execution_tool",
  "args": {
    "runtime": "output",
    "session": 1
  }
}

```

When you need to clean up resources or reset the environment state, invoke the `reset` runtime. This closes the specified session and discards all accumulated state:

```json
{
  "tool_name": "code_execution_tool",
  "args": {
    "runtime": "reset",
    "session": 1
  }
}

```

### Executing Node.js Code

```json
{
  "tool_name": "code_execution_tool",
  "args": {
    "runtime": "nodejs",
    "code": "console.log('Node says hi!')"
  }
}

```

## Technical Deep Dive: Session Architecture and Remote Execution

Under the hood, the `code_execution_tool` constructs a **`ShellWrap`** object that encapsulates either a **`LocalInteractiveSession`** or an **`SSHInteractiveSession`** (when remote execution is configured). This abstraction allows agents to execute code locally within the container or on remote hosts via SSH without changing the tool's interface.

The session lifecycle is managed through several key methods defined in [`python/tools/code_execution_tool.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/code_execution_tool.py):

- **`prepare_state`** — Initializes the execution environment and validates runtime parameters.
- **`terminal_session`** — Manages the interactive shell state for terminal runtimes.
- **`execute_python_code`** — Handles IPython wrapping and Python-specific execution logic.
- **`execute_nodejs_code`** — Interfaces with the Node.js helper script at [`/exe/node_eval.js`](https://github.com/agent0ai/agent-zero/blob/main//exe/node_eval.js).
- **`execute_terminal_command`** — Dispatches raw shell commands to the active session.

Because this is a **first-class built-in tool**, it is automatically registered in every agent's system prompt and requires no custom configuration to use.

## Summary

- Agent Zero provides a single, powerful built-in tool for code execution: **`code_execution_tool`**.
- The tool is implemented in [`python/tools/code_execution_tool.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/code_execution_tool.py) by the **`CodeExecution`** class.
- It supports **Python**, **Node.js**, and **Terminal/Shell** execution through distinct runtime modes.
- **Session management** allows persistent interactive shells across multiple tool calls, with support for output retrieval and session reset.
- The architecture supports both **local** (`LocalInteractiveSession`) and **remote** (`SSHInteractiveSession`) execution via the `ShellWrap` abstraction.
- As a built-in tool, it is automatically available to all agents without configuration.

## Frequently Asked Questions

### What programming languages does Agent Zero's built-in code execution tool support?

Agent Zero's `code_execution_tool` supports **Python** (via IPython), **Node.js** (JavaScript), and **shell/terminal** commands (Bash on Linux/macOS, PowerShell on Windows). The tool uses the `runtime` parameter to switch between these modes, wrapping Python code in `ipython -c` commands and Node.js code in a helper script located at [`/exe/node_eval.js`](https://github.com/agent0ai/agent-zero/blob/main//exe/node_eval.js).

### How does session management work in the Agent Zero code execution tool?

The tool implements **numbered sessions** (defaulting to `session: 0`) that maintain state across separate invocations. When using `runtime: "terminal"`, the session keeps an interactive shell alive, allowing you to run a command, later retrieve buffered output with `runtime: "output"`, and finally terminate the environment with `runtime: "reset"`. Set `allow_running: false` to prevent accidentally overwriting active sessions.

### Can Agent Zero execute code on remote machines using the built-in tools?

Yes, the `code_execution_tool` supports remote execution through the **`SSHInteractiveSession`** class. Under the hood, the tool constructs a `ShellWrap` object that can encapsulate either a `LocalInteractiveSession` (for container-local execution) or an `SSHInteractiveSession` (for remote hosts). This allows agents to execute Python, Node.js, or shell commands on remote servers without changing the tool's JSON interface.

### Is the code execution tool automatically available to all Agent Zero agents?

Yes, the `code_execution_tool` is a **first-class built-in capability** that is automatically registered in every agent's system prompt. Because it is defined in the core framework at [`python/tools/code_execution_tool.py`](https://github.com/agent0ai/agent-zero/blob/main/python/tools/code_execution_tool.py) and referenced in [`prompts/agent.system.tool.code_exe.md`](https://github.com/agent0ai/agent-zero/blob/main/prompts/agent.system.tool.code_exe.md), you do not need to install additional dependencies or configure custom tools to begin executing code.