人工智能AI AgentAgent 沙箱后端【免费下载链接】E2BOpen-source, secure environment with real-world tools for enterprise-grade agents.项目地址https://gitcode.com/gh_mirrors/e2/E2B点击查看免费下载导读本文围绕 E2B 开源仓库中的 code-interpreter-js 包 展开系统讲解如何通过e2b/code-interpreterJavaScript SDK 在云端安全、隔离的沙箱中运行 AI 生成的代码。读完本文你将掌握 SDK 的安装与 API Key 配置、Sandbox.runCode()的有状态代码执行、E2B客户端的多配置绑定以及执行结果、上下文Context、超时与错误处理的底层原理并能在真实 Agent 应用中直接落地使用。一、什么是 E2B Code InterpreterE2B 是一套开源基础设施它允许你在云端安全隔离的沙箱中运行 AI 生成的代码。所谓AI 生成的代码意味着代码内容本身不可信、不可预判——它们可能来自 LLM 的推理输出、用户输入或第三方插件因此必须在隔离环境中执行而不能直接跑在宿主机器上。e2b/code-interpreter是面向 JavaScript/TypeScript 的官方 SDK仓库源码位于 packages/code-interpreter-js它的定位是有状态的代码执行Stateful code execution见 package.json 中的 description。与一次性执行完就销毁的无状态模型不同它允许你在同一个沙箱中引用之前定义的变量、导入的模块和函数这与 Jupyter Notebook / IPython Kernel 的执行语义一致非常适合做数据分析、图表绘制、逐步推理等需要上下文的 Agent 任务。从 SDK 导出结构src/index.ts可以看到该包的核心能力包括Sandbox云沙箱的封装负责运行代码、管理执行上下文E2B绑定显式连接配置的客户端API Key、domain 等Context、Execution、Result、Logs、ExecutionError等执行模型各类图表类型Line、Bar、Pie、Scatter、BoxAndWhisker、SuperChart的数据结构。二、环境要求与安装 SDKe2b/code-interpreter对运行时版本有明确要求见 package.json 的 engines 字段Node.js20.18.1 21或22安装方式与普通 npm 包一致npm i e2b/code-interpreter该包的运行时依赖只有一个e2b核心 SDK包含连接配置、Sandbox 基类、Volume、Template、Secret 等资源因此安装非常轻量。构建产物同时提供 CommonJSdist/index.js与 ESMdist/index.mjs两种格式并自带 TypeScript 类型声明dist/index.d.ts。三、获取 API Key 并配置环境变量注册 E2B 账号并登录控制台在控制台的 API Keys 页面创建密钥形如e2b_***将其设置为环境变量E2B_API_KEYe2b_***顶层导出的Sandbox在创建实例时会自动从环境变量读取连接配置包括E2B_API_KEY、E2B_DOMAIN、E2B_SANDBOX_URL、E2B_DEBUG等。这意味着只要环境变量配置好代码里无需任何额外设置即可创建沙箱。注意API Key 是敏感凭证应通过环境变量或密钥管理服务注入切勿硬编码进源码或提交到版本库。四、快速开始在沙箱中运行第一段代码4.1 基础用法import { Sandbox } from e2b/code-interpreter const sbx await Sandbox.create() await sbx.runCode(x 1) const execution await sbx.runCode(x1; x) console.log(execution.text) // outputs 2这段代码演示了两个关键点Sandbox.create()创建并启动一个云端沙箱。默认使用code-interpreter-v1模板见 src/sandbox.ts 中defaultTemplate的覆写沙箱内预置了 Python 等代码解释器运行环境。runCode()是有状态的。第一次执行定义变量x 1第二次执行x1; x时能读取到之前的状态最终主结果text为2。这与 tests/basic.test.ts 中的断言一致runCode(x 1; x)的result.text等于1。4.2 runCode 的执行模型runCode的签名见 src/sandbox.ts支持两种调用形态// 方式一指定语言不指定则默认 Python sandbox.runCode(code, { language?: RunCodeLanguage }) // 方式二指定已创建的 Context sandbox.runCode(code, { context?: Context })context与language互斥同时传入会抛出InvalidArgumentErrorYou can provide context or language, but not both at the same time.。这一约束有对应的测试覆盖见 tests/contexts.test.ts。支持的RunCodeLanguage包括python、javascript、typescript、r、java、bash类型定义为(string {})的开放联合未来语言可扩展。从实现上看runCode会向沙箱内的 Jupyter 服务端口49999见 src/consts.ts发起POST /execute请求请求体携带code、context_id、language、env_vars字段随后按行流式读取响应体通过parseOutput将每一行 JSON 消息解析为 stdout、stderr、result、error 等事件见 src/messaging.ts 的parseOutput函数。五、理解执行结果Execution、Result 与 LogsrunCode返回一个Execution对象它是整个代码单元执行结果的聚合见 src/messaging.ts字段类型说明resultsResult[]单元格的展示结果交互式解释的末行表达式、display调用如 matplotlib 绘图等logsLogs执行期间打印到 stdout / stderr 的日志形如{ stdout: string[], stderr: string[] }errorExecutionError若执行出错则为错误对象否则为undefinedexecutionCountnumber单元格的执行序号textstring \| undefined便捷属性返回主结果isMainResult为 true 的那个 Result的文本表示其中Result与 IPython Kernel 的 execution semantics 保持一致一个结果可以同时包含多种表示形式src/messaging.tstext/html/markdown/svg/png/jpeg/pdf/latex/json/javascript同一结果的不同媒体类型dataDataFrame 等结构化数据chartE2B 特有的一等公民——图表数据后面详述extra非标准类型的额外字段raw未拆分的原始数据isMainResult是否为该单元格的主结果formats()返回该结果当前可用的全部媒体格式。而ExecutionError则携带name错误名如NameError、value错误信息、traceback原始堆栈三个字段。六、runCode 的完整选项回调、环境变量与超时RunCodeOpts见 src/sandbox.ts提供了完整的执行控制能力interface RunCodeOpts { onStdout?: (output: OutputMessage) Promiseany | any // stdout 流式回调 onStderr?: (output: OutputMessage) Promiseany | any // stderr 流式回调 onResult?: (data: Result) Promiseany | any // 每个 Result 出现时回调 onError?: (error: ExecutionError) Promiseany | any // 执行出错时回调 envs?: Recordstring, string // 本次执行的临时环境变量默认 {} timeoutMs?: number // 代码执行超时毫秒默认 60_000 requestTimeoutMs?: number // 请求超时毫秒默认 30_000 }6.1 流式回调runCode是流式的stdout、stderr、result 会随着执行推进实时触发回调而不是等全部结束后一次性返回。这在长耗时任务如逐步打印推理过程中尤为有用。const out: OutputMessage[] [] await sandbox.runCode(print(1), { onStdout: (msg) out.push(msg), }) // out[0].line 1\nOutputMessage包含line输出行文本、timestampUnix 纳秒时间戳、error是否为错误输出三个字段且实现了toString()方便直接打印见 src/messaging.ts。相关行为在 tests/callbacks.test.ts 与 tests/streaming.test.ts 中有完整验证onResult回调runCode(x 1; x, { onResult })触发 1 次且result.results[0].text 1onError回调runCode(xyz, { onError })触发 1 次错误名为NameErroronStdoutprint(hello)后result.logs.stdout为[hello\n]onStderr向sys.stderr打印后result.logs.stderr为[This is an error message\n]流式场景包含plt.show()绘图 末行表达式的代码会触发 2 次onResult一次绘图结果、一次主结果。6.2 每次执行的临时环境变量通过envs选项可以为单次执行注入临时环境变量不会污染沙箱的其他执行const result await sandbox.runCode(import os; os.getenv(FOO), { envs: { FOO: bar }, }) // result.results[0]?.text.trim() bar而未传envs的后续执行读不到该变量测试见 tests/envVars.test.ts。6.3 双重超时机制SDK 对单次执行设置了两段式超时实现见 src/sandbox.tsrequestTimeoutMs默认 30 秒等待沙箱返回响应头的超时。超过后 abort 请求抛出TimeoutErrorRequest timed out — the requestTimeoutMs option can be used to increase this timeout见 src/utils.ts 的formatRequestTimeoutErrortimeoutMs默认 60 秒开始接收响应体之后整个流式读取过程的超时。超过后同样抛出TimeoutErrorExecution timed out — the timeoutMs option can be used to increase this timeout。超时中断后沙箱本身不会被销毁。客户端断开连接会触发服务端中断内核后续执行仍然可用——这一行为由 tests/interrupt.test.ts 验证一个time.sleep(300)的长任务在timeoutMs: 3_000下被中断后等待服务端检测到断连再执行1 1依然返回2。七、上下文Context管理独立的代码执行环境除了默认上下文SDK 还支持创建、列出、删除和重启独立的执行上下文Context每个 Context 有自己的语言与工作目录状态彼此隔离。相关 API 全部在 src/sandbox.ts方法说明createCodeContext(opts?)创建上下文。cwd默认/home/userlanguage默认pythonrequestTimeoutMs默认 30 秒listCodeContexts()列出沙箱内全部上下文removeCodeContext(context \| id)删除指定上下文restartCodeContext(context \| id)重启上下文清空其中所有变量与状态典型使用场景const context await sandbox.createCodeContext({ language: python, cwd: /root }) await sandbox.runCode(x 1, { context }) // 在上下文中定义变量 await sandbox.restartCodeContext(context.id) // 重启上下文 const execution await sandbox.runCode(x, { context }) console.log(execution.error?.name) // NameError变量已不存在上述重启后变量消失的行为在 tests/contexts.test.ts 中有明确断言重启后执行x会得到NameErrorvalue为name x is not defined。默认沙箱预置了 python 与 javascript 两个语言上下文测试通过listCodeContexts()验证了这一点。Context 机制的价值在于你可以为不同的任务、租户或安全边界分配隔离的执行环境互不干扰同时复用沙箱资源避免频繁创建/销毁沙箱的开销。八、将配置绑定到 E2B 客户端8.1 为什么需要 E2B 客户端顶层导出的Sandbox从环境变量读取配置。但在真实的生产场景中一个进程里可能需要同时使用多个 API Key不同用户、不同项目不同的 domain如自建部署的 E2B 服务地址与全局环境变量不同的连接参数。此时就需要创建E2B客户端把配置显式绑定到客户端上再通过客户端暴露的资源类去操作import { E2B } from e2b/code-interpreter const client new E2B({ apiKey: e2b_***, domain: e2b.dev }) const sbx await client.Sandbox.create() const execution await sbx.runCode(x 1; x 1; x) // 核心资源同样绑定到该客户端的配置 const volume await client.Volume.create(my-volume) const exists await client.Template.exists(my-template) await client.Secret.create(openai-api-key, sk-***) // 资源类也可以解构出来像顶层导出一样使用 const { Sandbox } client const paginator Sandbox.list()8.2 绑定的语义细节从 src/client.ts 的实现可以看到几个关键设计浅拷贝防御构造函数会拷贝传入的opts避免调用方后续修改对象影响已绑定的配置headers与apiHeaders也会被拷贝。丢弃signalsignal用于取消单次请求如果绑定到客户端会被应用到每一次调用因此被显式删除而不是仅做类型上的排除。资源类绑定client.Sandbox是通过继承Sandbox并覆写静态boundOpts生成的子类Volume、Template、Secret则由核心客户端e2b包的CoreE2B绑定生成。优先级规则每次调用的显式选项 客户端的绑定选项 环境变量。也就是说即使客户端配置了默认 domain/API Key单次调用传入的参数依然优先。完全隔离多个客户端之间、客户端与顶层环境变量配置的导出之间互相隔离互不影响。客户端类上的 JSDoc 也明确注明了这一行为。九、错误处理与连接中断的健壮性9.1 错误响应分类SDK 对非 2xx 的响应做了分类处理见 src/messaging.ts 的extractError502抛出TimeoutError并提示这很可能是沙箱超时导致可通过创建沙箱时传入timeoutMs或调用.setTimeout()调整沙箱超时404抛出NotFoundError其他抛出SandboxError消息包含状态码、状态文本和响应体。9.2 执行中被杀死的兜底如果沙箱在请求进行中被杀死例如沙箱超时或被手动 killSDK 会检测连接关闭错误ECONNRESET、EPIPE、UND_ERR_SOCKET以及 Bun/Deno/workerd 等运行时形态各异的断连错误见 src/utils.ts 的isConnectionClosedError随后检查沙箱isRunning()状态若确认沙箱已不在运行则抛出带明确说明的TimeoutErrorThe sandbox was killed while the request was in progress. This can happen when the sandbox times out or is killed manually. You can modify the sandbox timeout by passing timeoutMs when starting the sandbox or calling .setTimeout on the sandbox with the desired timeout.这一行为由 tests/killedSandbox.test.ts 验证对一个time.sleep(300)的进行中执行调用sandbox.kill()runCode会以TimeoutError拒绝且错误消息匹配/sandbox was killed while the request was in progress/。十、沙箱连接重连与 URL 解析10.1 通过 sandboxId 重连沙箱创建后会获得一个sandboxId你可以在任何时间、任何进程甚至重启后的服务中通过它重新连接const sbx await Sandbox.connect(sandbox.sandboxId) const result await sbx.runCode(x 1; x)重连后沙箱内的状态已安装的依赖、已定义的变量仍然保留。该能力在 tests/reconnect.test.ts 中有验证。10.2 Jupyter URL 的解析规则jupyterUrl的解析逻辑src/sandbox.ts在不同场景下有不同结果tests/sandboxUrl.test.ts 给出了完整的对照场景解析结果受支持域名e2b.apphttps://sandbox.e2b.app统一沙箱端点指定sandboxDomain: e2b.devhttps://sandbox.e2b.dev优先于配置域名不受支持的域名example.devhttps://49999-test-sandbox-id.example.dev按端口分片的沙箱主机debug: truehttp://localhost:49999本地 envd 调试显式sandboxUrl选项直接使用该 URL环境变量E2B_SANDBOX_URL直接使用该 URL十一、图表数据结果的一等公民e2b/code-interpreter的一大特色是结构化图表数据。当沙箱内代码生成 matplotlib 等图表时Result.chart会携带可序列化的图表结构而不是只有 PNG 图片方便前端用任意图表库如 ECharts、Plotly重新渲染。支持的图表类型见 src/charts.tsline折线图、scatter散点图、bar柱状图、pie饼图、box_and_whisker箱线图、superchart图表组合内部嵌套多个子图坐标轴刻度、标签、比例尺类型linear、datetime、categorical、log、symlog、logit、function、functionlog、asinh都有对应的结构化字段。deserializeChart负责把原始数据还原为类型化的图表对象superchart会递归反序列化内部子图。所有图表类型均从 src/index.ts 导出可直接用于类型安全的渲染代码。十二、测试体系SDK 行为的验证依据该包的测试位于 tests 目录使用 Vitest 编写覆盖了上文提到的全部核心行为basic.test.ts基础执行与结果断言contexts.test.tsContext 的创建、列出、删除、重启及参数互斥校验callbacks.test.tsonResult/onError/onStdout/onStderr回调envVars.test.ts单次执行的临时环境变量streaming.test.ts流式输出与流式 Resultinterrupt.test.ts超时中断后沙箱可继续使用killedSandbox.test.ts执行中被杀死时的错误语义reconnect.test.ts通过 sandboxId 重连sandboxUrl.test.tsJupyter URL 解析规则utils.test.ts流式响应体按行解析的 UTF-8 健壮性包括分块边界、未终止末行、残缺 UTF-8 序列。此外测试基建tests/setup.ts还展示了沙箱的完整生命周期管理每个测试通过Sandbox.create(template)创建沙箱、注入测试元数据并在用例结束后调用sandbox.kill()释放资源E2B_DEBUG环境变量用于切换本地 envd 调试模式。这套 fixture 本身就是生产代码中创建→使用→销毁沙箱的最佳实践范本。十三、小结与下一步本文完整覆盖了e2b/code-interpreter从安装、鉴权到有状态代码执行的完整链路安装与鉴权npm i e2b/code-interpreterE2B_API_KEY环境变量快速执行Sandbox.create()runCode()状态在多次执行间保留执行模型Execution/Result/Logs/ExecutionError的字段与语义精细控制流式回调、临时环境变量、双重超时timeoutMs/requestTimeoutMs上下文管理createCodeContext/listCodeContexts/removeCodeContext/restartCodeContext多配置隔离E2B客户端绑定 API Key 与 domain单次调用选项优先健壮性错误分类、执行中杀死的兜底提示、sandboxId 重连。如果想在真实项目中进一步实践可以阅读包的入口导出 src/index.ts了解全部可用的类型与函数对照 src/sandbox.ts 与 src/messaging.ts 深入理解执行协议结合 tests 目录下的测试用例把沙箱创建/销毁、错误处理、重连等模式复用到自己的 Agent 工程中。需要注意使用云端沙箱会产生真实资源消耗请务必在代码路径中确保沙箱被正确释放如finally中调用kill()并为长任务设置合理的超时避免资源泄漏。赞分享人工智能AI AgentAgent 沙箱后端【免费下载链接】E2BOpen-source, secure environment with real-world tools for enterprise-grade agents.项目地址https://gitcode.com/gh_mirrors/e2/E2B点击查看免费下载相关推荐OpenSandbox Code Interpreter JavaScript/TypeScript SDK 实战在安全沙箱中运行 Python、Java、Go 代码OpenSandbox Code Interpreter JavaScript/TypeScript SDK 实战在安全沙箱中运行 Python、Java、G人工智能AI 应用Agent 沙箱云原生后端代码智能体E2B 沙箱快速上手指南用 JavaScript 与 Python SDK 运行 AI 生成代码E2B 沙箱快速上手指南用 JavaScript 与 Python SDK 运行 AI 生成代码 E2B 是一个开源的云基础设施它让开发者能够把 AI 生成人工智能AI AgentAgent 沙箱后端OpenSandbox Code Interpreter Python SDK 实战多语言安全沙箱代码执行完全指南OpenSandbox Code Interpreter Python SDK 实战多语言安全沙箱代码执行完全指南 OpenSandbox 为 AI Agen人工智能AI 应用Agent 沙箱云原生后端代码智能体上一篇如何快速掌握八大网盘直链下载开源工具LinkSwift完全指南下一篇vscode-live-server 使用 FAQ从项目配置、动态页面到多端访问的完整实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考