主题
E2B 沙箱工具
E2BExecTool、E2BPythonTool和E2BFileTool让 CrewAI 智能体可以在隔离、临时的 E2B 远程沙箱中获得 shell、Python 和文件系统访问能力。
E2B 沙箱工具
描述
E2B 沙箱工具让 CrewAI 智能体可以在由 E2B 托管的隔离、临时虚拟机中运行代码。三个工具共享同一个基类和连接模型：
E2BExecTool— 执行 shell 命令。E2BPythonTool— 在 Jupyter 风格的代码解释器中执行 Python（返回 stdout、stderr，以及图表、数据帧、HTML、SVG 和 PNG 等丰富结果）。E2BFileTool— 执行文件系统操作（read、write、append、list、delete、mkdir、info、exists），包括通过 base64 处理二进制内容。
当你希望让智能体能够运行任意代码或执行文件操作，同时不暴露宿主环境时，请使用这些工具。
安装
为 crewai-tools 安装 e2b extra，并设置你的 E2B API 密钥：
shell
uv add "crewai-tools[e2b]"shell
export E2B_API_KEY="e2b_..."工具
E2BExecTool
通过 sandbox.commands.run 在沙箱内运行 shell 命令。
参数
command: str— 必填。要执行的 shell 命令。cwd: str | None— 可选。命令的工作目录。envs: dict[str, str] | None— 可选。每次调用的环境变量。timeout: float | None— 可选。超时时间，单位为秒。
返回
json
{
"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— 可选。超时时间，单位为秒。
返回
json
{
"text": "...",
"stdout": "...",
"stderr": "...",
"error": null,
"results": [],
"execution_count": 1
}results 可以包含该单元格生成的图表、数据帧、HTML、SVG 和 PNG 输出。
E2BFileTool
在沙箱内执行文件系统操作。写入时自动创建父目录，并通过 base64 处理二进制内容。
参数
action: "read" | "write" | "append" | "list" | "delete" | "mkdir" | "info" | "exists"— 必填。path: str— 必填。沙箱内的目标路径。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— 自定义沙箱模板或快照。persistent: bool— 默认False。参见沙箱模式。sandbox_id: str | None— 附加到现有沙箱。sandbox_timeout: int— 空闲超时时间，单位为秒。默认300。envs: dict[str, str] | None— 在创建沙箱时注入的环境变量。metadata: dict[str, str] | None— 在创建沙箱时附加的元数据。
沙箱模式
| 模式 | 如何激活 | 沙箱生命周期 |
|---|---|---|
| 临时（默认） | persistent=False | 每次 _run 调用都会创建并销毁一个新的沙箱。 |
| 持久化 | persistent=True | 沙箱在首次调用时延迟创建，并在进程退出时通过 atexit 销毁。 |
| 附加 | sandbox_id="sbx_..." | 工具附加到现有沙箱，并且永远不会销毁它。 |
一次性任务使用临时模式 — 它可以将影响范围降至最低。当智能体需要在多次工具调用之间保持状态（例如 shell 会话以及对同一批文件进行文件系统操作）时，使用持久化模式。当外部系统管理沙箱生命周期时，使用附加模式。
示例
一次性 Python（临时模式）
python
from crewai_tools import E2BPythonTool
tool = E2BPythonTool()
result = tool.run(code="print(sum(range(10)))")持久化 shell + 文件系统会话
python
from crewai_tools import E2BExecTool, E2BFileTool
exec_tool = E2BExecTool(persistent=True)
file_tool = E2BFileTool(persistent=True)当进程退出时，两个工具都会通过 atexit 清理沙箱。
附加到现有沙箱
python
from crewai_tools import E2BExecTool
tool = E2BExecTool(sandbox_id="sbx_...")该工具不会销毁它所附加的沙箱。
自定义模板、超时、环境变量和元数据
python
from crewai_tools import E2BExecTool
tool = E2BExecTool(
persistent=True,
template="my-custom-template",
sandbox_timeout=600,
envs={"MY_FLAG": "1"},
metadata={"owner": "crewai-agent"},
)完整智能体示例
python
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()安全注意事项
这些工具让智能体可以在沙箱内获得任意 shell、Python 和文件系统访问权限。沙箱将执行与宿主隔离，但你仍应将工具输出视为不可信，并在设计时考虑提示词注入：
- 临时模式是主要的影响范围控制手段 — 每次
_run调用都会获得一个全新 VM。除非需要持久化状态，否则优先使用它。 - 持久化和附加的沙箱会跨调用累积状态。任何注入其中的内容（凭据、token、文件）都可被后续每次工具调用访问，包括输入受到不可信内容影响的调用。
- 避免将密钥注入智能体可读取或泄露的长期存活沙箱。使用短期凭据和所需的最小权限范围。
sandbox_timeout限制空闲时间，但不限制总执行时间。将其设置为适合你工作负载的最小值。