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

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. 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.

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 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:

{
  "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:

{
  "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:

{
  "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:

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

Executing Node.js Code

{
  "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:

• 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.
• 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 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.

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 and referenced in prompts/agent.system.tool.code_exe.md, you do not need to install additional dependencies or configure custom tools to begin executing code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}