Skip to main content

Overview

E2BTools extends ToolKit and uses the E2B cloud sandbox for running code, shell commands, and managing files in an isolated environment. Supports Python, JavaScript, Java, R, and Bash.
ToolKit: E2BTools inherits from ToolKit. You get all base behavior (e.g. include_tools, exclude_tools, timeout, use_async). See Creating ToolKit for the full API.
Required: Set E2B_API_KEY (env or .env). Install: uv pip install e2b-code-interpreter.
Tools (10): e2b_run_code, e2b_run_command, e2b_install_packages, e2b_upload_file, e2b_download_file, e2b_list_files, e2b_write_file, e2b_read_file, e2b_get_sandbox_info, e2b_shutdown_sandbox. Use ToolKit’s exclude_tools / include_tools to limit which tools the agent sees.
All tools are prefixed with e2b_ (e.g. e2b_run_code, e2b_write_file) to avoid name collisions with local filesystem tools or other sandbox toolkits when used alongside AutonomousAgent.

Examples

Basic: Agent with E2B

from upsonic import Agent, Task
from upsonic.tools.custom_tools.e2b import E2BTools

agent = Agent(model="openai/gpt-4o", tools=[E2BTools()])
task = Task(description="Write a Python function to check if a number is prime, then test it with 17 and 20.")
result = agent.print_do(task)
print(result)

AutonomousAgent: Local Filesystem + Remote Sandbox

The most powerful pattern: the agent edits files locally in the workspace, but all code execution happens in a secure remote sandbox.
from upsonic import AutonomousAgent, Task
from upsonic.tools.custom_tools.e2b import E2BTools

agent = AutonomousAgent(
    model="openai/gpt-4o",
    workspace="/path/to/project",
    enable_filesystem=True,   # local: write_file, edit_file, read_file, etc.
    enable_shell=False,       # disable local shell execution
    tools=[E2BTools()],       # remote: e2b_run_code, e2b_run_command, e2b_install_packages
)

task = Task(description="Read main.py, then run it in the sandbox and fix any errors.")
result = agent.print_do(task)
CapabilityWhere it runsTools
File write/edit/deleteLocal workspace (sandboxed)write_file, edit_file, delete_file, move_file, copy_file
File read/searchLocal workspace (sandboxed)read_file, list_files, search_files, grep_files
Code executionRemote E2B sandboxe2b_run_code (Python/JS/Java/R/Bash)
Shell commandsRemote E2B sandboxe2b_run_command
Package installRemote E2B sandboxe2b_install_packages
Sandbox file opsRemote E2B sandboxe2b_write_file, e2b_read_file, e2b_list_files
File transferLocal ↔ Remotee2b_upload_file, e2b_download_file

Advanced: Custom Sandbox Options

from upsonic import Agent, Task
from upsonic.tools.custom_tools.e2b import E2BTools

tools = E2BTools(
    timeout=600,                          # 10-minute sandbox lifetime
    sandbox_options={
        "envs": {"MY_API_KEY": "sk-..."},  # env vars available in sandbox
        "metadata": {"project": "demo"},
    },
    exclude_tools=["e2b_shutdown_sandbox"],  # prevent agent from killing sandbox
)

agent = Agent(model="anthropic/claude-sonnet-4-6", tools=[tools])
task = Task(description="Install pandas and matplotlib, then create a bar chart of sales data.")
result = agent.print_do(task)

Multi-language Code Execution

from upsonic import Agent, Task
from upsonic.tools.custom_tools.e2b import E2BTools

agent = Agent(model="openai/gpt-4o", tools=[E2BTools()])

# Python
task = Task(description="Use e2b_run_code with language='python' to compute factorial of 20.")
agent.print_do(task)

# JavaScript
task = Task(description="Use e2b_run_code with language='javascript' to sort [5,3,8,1] and print the result.")
agent.print_do(task)

# Bash
task = Task(description="Use e2b_run_code with language='bash' to list all environment variables.")
agent.print_do(task)

Parameters

ParameterTypeDefaultDescription
api_keystr | Nonefrom env E2B_API_KEYE2B API key.
timeoutint300Sandbox lifetime in seconds. Max 86400 (Pro) or 3600 (Hobby).
sandbox_optionsdict | NoneNoneAdditional options for Sandbox.create() (e.g. template, envs, metadata).

Tools Reference

Code Execution

ToolDescription
e2b_run_codeExecute code in the sandbox. Supports python, javascript, java, r, bash. Returns logs, results, errors, and generated images.
e2b_run_commandRun a shell command in the sandbox. Returns stdout, stderr, and exit code.
e2b_install_packagesInstall packages via pip (Python) or npm (JavaScript).

Sandbox File Operations

ToolDescription
e2b_write_fileWrite text content to a file in the sandbox.
e2b_read_fileRead a text file from the sandbox.
e2b_list_filesList files and directories in the sandbox.
e2b_upload_fileUpload a local file to the sandbox.
e2b_download_fileDownload a file from the sandbox to the local system.

Sandbox Management

ToolDescription
e2b_get_sandbox_infoGet sandbox status: sandbox_id, template_id, started_at, end_at.
e2b_shutdown_sandboxKill the sandbox and release resources.