Guide · 使用教程
E2B AI 代码沙箱教程：隔离执行、出网限制、超时清理与人工验收
用 E2B Sandbox 为 AI Agent 增加受控代码执行：先跑脱敏样本，再检查网络、超时、日志、结果校验和资源回收。
目标与前提
本教程搭建一条最小的“生成代码—规则检查—沙箱执行—人工验收”流程。先用固定测试代码，不直接接真实模型与生产数据。需要 Python、E2B 账户和 API key。SDK 用于创建沙箱；模型提供商的 API key 是另一套凭据，两者不要混放，也不要写进提示词、仓库或沙箱文件。
E2B 的沙箱提供隔离执行环境，但不会自动判断用户是否有权读取数据或执行外部动作。应用侧仍须负责身份、租户边界、审批、预算和审计。以下代码展示 SDK 调用形态，具体版本请以官方文档和安装包为准；上线前必须在自己的账户实测。
第一步：准备最小环境
在本地 Python 虚拟环境安装官方 SDK，并把 E2B API key 放在进程环境变量中。不要将密钥直接硬编码到示例脚本或提交到 Git。
python -m venv .venv
source .venv/bin/activate
pip install e2b
export E2B_API_KEY='从 E2B 控制台获取的测试密钥'
为试点账户设置账单提醒和最小权限。测试代码只使用公开、脱敏的数据。没有账户密钥时可先审查代码与流程，但无法验证真实沙箱行为。
第二步：执行固定的只读样本
官方 Python SDK 提供 Sandbox.create()、sandbox.commands.run() 和 sandbox.kill()。下面禁用沙箱出网，将会话设为 120 秒，命令连接超时设为 30 秒，并在 finally 回收沙箱。初次执行只计算 2+2，不触碰本机文件或外部 API。
from e2b import Sandbox
sandbox = Sandbox.create(
timeout=120,
allow_internet_access=False,
metadata={"purpose": "sandbox-smoke-test"},
)
try:
result = sandbox.commands.run(
"python -c 'print(2 + 2)'",
timeout=30,
)
print(result.stdout)
finally:
sandbox.kill()
预期标准输出为 4。如果 SDK 返回错误、超时或网络异常，应保留任务 ID、沙箱 ID、命令、耗时及异常类型供排查；日志里不要记录 API key。命令连接超时与会话生命周期是不同概念，必须分别测试，并核对错误后沙箱是否仍在计费。
第三步：把模型接入审批点
不要把模型原始回答拼成 Shell 命令直接运行。先要求模型只输出单一代码块或结构化调用，再检查语言、长度、依赖和允许的输入文件。第一版只允许运行已审阅的 Python 片段，禁止外部下载、安装任意包、访问生产服务或读取未授权文件。应用的执行器将代码作为文件或受控命令送入沙箱；对用户发起的每次运行保留审计记录。
如果 Agent 想调用“发送邮件、写数据库、删除文件”工具，在调用前由应用侧生成明确的审批对象：目标、操作、影响范围和预览。审批拒绝时不创建执行任务；批准后也只发放该动作所需的短期凭据。沙箱中的代码输出只作为数据，不作为新的系统指令。
第四步：核对网络与数据边界
E2B Python SDK 的 allow_internet_access 可控制沙箱是否允许互联网访问。先用一个公开测试域名确认禁网设置确实阻断，再分别测试企业内部地址、对象存储和模型 API。不要把“禁用互联网”直接推断为所有内部网络都已隔离；按所选云、BYOC 或自部署路径核对网络拓扑与策略。
测试文件必须先脱敏。若需要上传真实数据，应先确定谁能上传、文件留存多久、是否进入模型或日志、下载链接如何失效。对每个任务建立独立沙箱或等价隔离策略，禁止不同用户复用含敏感数据的状态。对输出设置大小与格式限制，避免大日志拖垮上游服务。
第五步：六项上线验收
- 正常任务：结果正确、可关联输入和沙箱 ID，资源与费用可追踪。
- 语法错误：向用户返回可理解的错误，原始堆栈与密钥不外泄。
- 超时与取消：命令停止，会话按预期销毁，不留下运行计费资源。
- 网络拒绝：未授权域名与端口访问失败，且日志可追溯。
- 大输出与并发：限制结果大小，达到并发上限时排队或拒绝，不能无限重试。
- 高风险动作：审批拒绝时不执行；批准后也仅能操作批准的目标。
最后以“通过人工验收的任务数”为分母计算费用：E2B 基础费、CPU/内存运行费、存储、模型 token、重试和维护工时。Hobby 的一次性额度不是永久免费配额；Pro 的月费也不包含全部运行成本。
官方资料
常见问题
- E2B Sandbox 会自动调用模型吗？
- 不会。沙箱负责执行环境；模型调用、工具调度、规则检查和审批都由应用设计。
- E2B_API_KEY 能交给 Agent 代码使用吗？
- 不建议。应由可信的服务端保管并调用 SDK，不把长期密钥写进模型输入或沙箱文件。
- 设置 allow_internet_access=False 就足够安全吗？
- 不够。还需验证网络拓扑、文件权限、密钥、资源上限、日志和外部写入接口。
- 命令超时后沙箱会自动销毁吗？
- 不能仅凭命令超时假定。命令连接时间与沙箱生命周期不同，要在异常路径执行清理并回读状态。
- 什么时候需要人工审批？
- 当 Agent 要发送消息、修改文件、写数据库或调用其他有副作用的工具时，应在应用侧先审批目标和影响范围。
- 如何计算真实费用？
- 将基础月费、按秒 CPU/内存费用、存储、模型调用、失败重试和维护工时相加，再除以通过验收的任务数。