E2B Sandbox Tools

E2B Sandbox Tools

描述

E2B sandbox 工具让 CrewAI agents 能在由 E2B 托管的隔离、短暂存在的虚拟机中运行代码。三种工具共享同一个基类和连接模型：

• E2BExecTool - 执行 shell 命令。
• E2BPythonTool - 在类似 Jupyter 的代码解释器中执行 Python（返回 stdout、stderr，以及图表、dataframes、HTML、SVG 和 PNG 等丰富结果）。
• E2BFileTool - 在 sandbox 内执行文件系统操作（read、write、append、list、delete、mkdir、info、exists），也支持通过 base64 处理二进制内容。

当你想让 agent 运行任意代码或执行文件操作，但又不想暴露宿主环境时，这些工具非常适合。

安装

安装 crewai-tools 的 e2b extra 并设置 E2B API key：

uv add "crewai-tools[e2b]"

export E2B_API_KEY="e2b_..."

工具

E2BExecTool

通过 sandbox.commands.run 在 sandbox 中运行 shell 命令。

参数

• command: str - 必填。要执行的 shell 命令。
• cwd: str | None - 可选。命令的工作目录。
• envs: dict[str, str] | None - 可选。单次调用的环境变量。
• timeout: float | None - 可选。超时时间（秒）。

返回

{
  "exit_code": 0,
  "stdout": "...",
  "stderr": "...",
  "error": null
}

E2BPythonTool

使用 e2b_code_interpreter SDK，在 Jupyter 风格的代码解释器中运行 Python 代码。

参数

• code: str - 必填。要执行的代码。
• language: str | None - 可选。语言标识符（默认是 Python）。
• envs: dict[str, str] | None - 可选。单次调用的环境变量。
• timeout: float | None - 可选。超时时间（秒）。

返回

{
  "text": "...",
  "stdout": "...",
  "stderr": "...",
  "error": null,
  "results": [],
  "execution_count": 1
}

results 可以包含单元格生成的图表、dataframes、HTML、SVG 和 PNG 输出。

E2BFileTool

在 sandbox 中执行文件系统操作。写入时会自动创建父目录，并通过 base64 处理二进制内容。

参数

• action: "read" | "write" | "append" | "list" | "delete" | "mkdir" | "info" | "exists" - 必填。
• path: str - 必填。sandbox 中的目标路径。
• content: str | None - 可选。write / append 的内容。binary=True 时会以 base64 编码。
• binary: bool - 可选。将 content 视为二进制（base64）。默认 False。
• depth: int - 可选。list 的递归深度。

共享参数（E2BBaseTool）

这三种工具都接受相同的连接 / 生命周期参数：

• api_key: SecretStr | None - 回退到 E2B_API_KEY 环境变量。
• domain: str | None - 回退到 E2B_DOMAIN 环境变量。
• template: str | None - 自定义 sandbox 模板或快照。
• persistent: bool - 默认 False。见 Sandbox modes。
• sandbox_id: str | None - 连接到已有 sandbox。
• sandbox_timeout: int - 空闲超时时间（秒）。默认 300。
• envs: dict[str, str] | None - sandbox 创建时注入的环境变量。
• metadata: dict[str, str] | None - sandbox 创建时附加的元数据。

Sandbox 模式

Mode	How to activate	Sandbox lifetime
Ephemeral (default)	persistent=False	每次 _run 调用都会创建新的 sandbox，并在调用结束时销毁。
Persistent	persistent=True	第一次调用时懒创建 sandbox，并在进程退出时通过 atexit 销毁。
Attach	sandbox_id="sbx_..."	工具连接到已有 sandbox，并且不会销毁它。

临时模式适合一次性任务 - 它能把影响范围降到最低。需要 agent 在多次工具调用之间保持状态时，使用持久模式（例如在同一组文件上同时使用 shell session 和文件操作）。外部系统管理 sandbox 生命周期时，使用 attach 模式。

示例

一次性 Python（ephemeral）

from crewai_tools import E2BPythonTool

tool = E2BPythonTool()
result = tool.run(code="print(sum(range(10)))")

持久 shell + 文件系统会话

from crewai_tools import E2BExecTool, E2BFileTool

exec_tool = E2BExecTool(persistent=True)
file_tool = E2BFileTool(persistent=True)

当进程退出时，这两个工具都会通过 atexit 清理 sandbox。

连接到已有 sandbox

from crewai_tools import E2BExecTool

tool = E2BExecTool(sandbox_id="sbx_...")

该工具不会销毁它连接上的 sandbox。

自定义模板、超时、环境变量和元数据

from crewai_tools import E2BExecTool

tool = E2BExecTool(
    persistent=True,
    template="my-custom-template",
    sandbox_timeout=600,
    envs={"MY_FLAG": "1"},
    metadata={"owner": "crewai-agent"},
)

完整 agent 示例

from crewai import Agent, Crew, Process, Task
from crewai_tools import E2BPythonTool

python_tool = E2BPythonTool()

analyst = Agent(
    role="Data Analyst",
    goal="Run Python in a sandbox to answer analytical questions",
    backstory="An analyst who delegates computation to an isolated E2B sandbox.",
    tools=[python_tool],
    verbose=True,
)

task = Task(
    description="Compute the mean of [1, 2, 3, 4, 5] and return the result.",
    expected_output="The numerical mean.",
    agent=analyst,
)

crew = Crew(agents=[analyst], tasks=[task], process=Process.sequential)
result = crew.kickoff()

安全注意事项

这些工具会让 agent 在 sandbox 内获得任意 shell、Python 和文件系统访问权限。sandbox 会将执行与宿主环境隔离开，但你仍应把工具输出视为不可信，并在设计中考虑 prompt injection：

• 临时模式是主要的影响范围控制手段 - 每次 _run 调用都会获得一个新的 VM。除非确实需要持久状态，否则优先使用它。
• 持久和已连接的 sandbox 会在多次调用之间累积状态。任何注入其中的内容（凭据、token、文件）都可能被后续每次工具调用访问到，包括那些输入受不可信内容影响的调用。
• 不要把秘密信息注入长生命周期 sandbox，因为 agent 可能会读取或外泄它们。请使用短期凭据，并限制到最小必要范围。
• sandbox_timeout 只限制空闲时长，并不限制总执行时间。应把它设为能满足工作负载的最小值。