Skip to main content

使用 E2B SDK

OpenKruise Agents 的 sandbox-manager 组件支持两种 E2B 接入协议：原生 E2B 协议和私有协议。

sandbox-manager 的日常 E2E 回归测试通过 e2b-code-interpreter == 2.4.1 / e2b == 2.8.1 进行，同时通过 latest 版本测试兼容性。 更新版本的新功能会逐步适配，如果有功能需求，请通过 GitHub 提交 issue。

私有协议与原生协议的对比：

假设您配置的 E2B_DOMAIN 是 your.domain.com

原生协议私有协议
api.your.domain.comyour.domain.com/kruise/api
<port>-<sid>.your.domain.comyour.domain.com/kruise/<sid>/<port>

关于 E2B_DOMAIN 环境变量的重要说明​

非常重要：sandbox-manager 的 E2B_DOMAIN 环境变量必须与客户端设置相同。 您可以使用 kubectl edit deploy -n sandbox-system sandbox-manager 编辑你的 deployment 修改服务端环境变量。

如何配置服务端（sandbox-manager）的 E2B_DOMAIN​

方法 1：通过 Helm 配置（推荐）​

在通过 Helm 安装或升级 Sandbox Manager 时，您可以使用 e2b.domain 参数来设置 E2B_DOMAIN：

helm install agents-sandbox-manager openkruise/agents-sandbox-manager \
  -n sandbox-system \
  --set e2b.domain=your.domain.com \
  --set e2b.adminApiKey=<your-api-key> \
  --set ingress.className=<your-ingress-class>

方法 2：通过手动 Patch 配置​

您可以在运行 make deploy-sandbox-manager 之前通过编辑以下文件来配置服务端的 E2B_DOMAIN：

如何配置客户端（E2B SDK）的 E2B_DOMAIN​

您可以通过设置环境变量来配置客户端的 E2B_DOMAIN：

export E2B_DOMAIN=your.domain.com

特殊场景​

1. 带端口的域名​

对于 Ingress 网关不使用默认 HTTP 端口（80 或 443）的场景。例如，如果域名是 your.domain.com:8080：

  • 客户端：设置环境变量 E2B_DOMAIN=your.domain.com:8080
  • 服务端：

如何安装证书​

如果您需要通过 HTTPS 访问 sandbox-manager，需要安装 TLS 证书。建议使用可信证书。如果您没有可信证书，可以使用自签名证书，请参考以下文档：

您可以使用以下命令安装证书：

# ingress-nginx 示例，根据您的 ingress controller 进行调整
kubectl create secret tls sandbox-manager-tls \
          --cert=fullchain.pem \
          --key=privkey.pem -n sandbox-system

推荐的 sandbox-manager 集成方式​

1. 使用原生协议集成​

这是最标准、最原生的集成方式，但配置门槛也最高，通常需要手动部署。

  1. 客户端配置环境变量：

    # sandbox-manager 容器的 E2B_DOMAIN 环境变量应设置为相同值
    export E2B_DOMAIN=your.domain.com
    export E2B_API_KEY=<your-api-key>

  2. 在您的 DNS 提供商处将通配符域名 *.your.domain.com 解析到 sandbox-manager 的 ingress 端点

  3. 安装通配符证书 *.your.domain.com

2. 私有协议从集群外通过 HTTPS 访问​

这种方式可以降低部署门槛，将泛域名替换为了单域名。

  1. 客户端配置环境变量： 
    # sandbox-manager 容器的 E2B_DOMAIN 环境变量应设置为相同值
    export E2B_DOMAIN=your.domain.com
    export E2B_API_KEY=<your-api-key>
  2. 修改客户端： 
    from kruise_agents.patch_e2b import patch_e2b
    patch_e2b(https=True)
  3. 在您的 DNS 提供商处将单个域名 your.domain.com 解析到 sandbox-manager 的 ingress 端点
  4. 安装单个域名证书 your.domain.com

3. 使用 E2B URL 参数实现集群内访问​

通过 E2B SDK 原生支持的 URL 参数直接连接集群内的 sandbox-manager，无需域名、证书或私有协议 patch。要求 e2b >= 2.7.0。

  1. 确保客户端（agent）和 sandbox-manager 在同一集群中。
  2. 客户端配置环境变量： 
    export E2B_API_URL="http://sandbox-manager.sandbox-system.svc.cluster.local:8080"
    # 如果未安装外置的流量网关 sandbox-gateway，可以将下方 service 替换为 sandbox-manager
    # 以继续使用 sandbox-manager 内置的流量代理（不推荐）
    export E2B_SANDBOX_URL="http://sandbox-gateway.sandbox-system.svc.cluster.local:7788"
    export E2B_API_KEY=<your-api-key>
  3. 使用 E2B SDK 创建 Sandbox，无需额外 patch： 
    from e2b import Sandbox

    # E2B_API_URL 和 E2B_SANDBOX_URL 会自动从环境变量读取
    sandbox = Sandbox()
    print(sandbox.get_host(8000))  # 获取 Sandbox 内服务的访问地址
    sandbox.kill()

⚠️ 限制说明：上层库 e2b-code-interpreter 和 e2b-desktop 的以下扩展功能不读取 E2B_API_URL / E2B_SANDBOX_URL 环境变量，因此不支持此接入方式：

e2b-code-interpreter：

  • Sandbox.run_code
  • Sandbox.create_code_context
  • Sandbox.remove_code_context
  • Sandbox.list_code_contexts
  • Sandbox.restart_code_context

e2b-desktop：

  • desktop.stream.get_url
  • desktop.stream.start

4. 私有协议集群内访问​

这种方式可以快速自动化部署，无需配置域名和证书。仅推荐用于 E2E 测试场景，或经过严格评估后使用。

  1. 确保客户端（agent）和 sandbox-manager 在同一集群中。
  2. 客户端配置环境变量： 
    # sandbox-manager 容器的 E2B_DOMAIN 环境变量应设置为相同值
    export E2B_DOMAIN=sandbox-manager.sandbox-system.svc.cluster.local
    export E2B_API_KEY=<your-api-key>
  3. 修改客户端并禁用 HTTPS： 
    from kruise_agents.patch_e2b import patch_e2b
    patch_e2b(https=False)

5. 端口转发 sandbox-manager 到本地机器​

  1. 客户端配置环境变量： 
    # sandbox-manager 容器的 E2B_DOMAIN 环境变量应设置为相同值
    export E2B_DOMAIN=localhost
    export E2B_API_KEY=<your-api-key>
  2. 端口转发 sandbox-manager 到本地机器： 
    sudo kubectl port-forward services/sandbox-manager 80:7788 -n sandbox-system
  3. 修改客户端： 
    from kruise_agents.patch_e2b import patch_e2b
    patch_e2b(https=False)

E2B 兼容性说明​

⚠️ 重要：commands.run（命令执行）和文件系统 read/write API 需要在 Sandbox 中注入 agent-runtime 组件。请确保你的 SandboxSet 已配置 runtimes: [{name: agent-runtime}]。详情请参考运行时注入文档。

API分类API参数兼容程度说明
生命周期管理create部分兼容网络访问控制、原地变配待实现
get_info完全兼容
list完全兼容
kill完全兼容
pause完全兼容考虑到容器生态的效率问题，当前 pause 的实现为异步接口
resume完全兼容
connect完全兼容
set_timeout完全兼容设置 Sandbox 超时时间（TTL），等价于 E2B 的 Refresh sandbox API
代码运行run_code完全兼容主容器内需要运行e2b-code-interpreter
命令执行commands.run完全兼容需要通过运行时注入agent-runtime组件
文件系统read/write完全兼容需要通过运行时注入agent-runtime组件
upload_url/download_url不支持通过预签名url上传下载待实现
日志logs不支持Sandbox 日志获取待实现
监控指标metrics不支持Sandbox 监控指标获取待实现
网络network不支持Sandbox 网络配置（出口规则）待实现
生命周期事件https://api.e2b.app/events/sandboxes/{sbx.sandbox_id}不支持生命周期事件待实现
快照管理snapshots完全兼容具体快照效果依赖于 Checkpoint 实现
模板管理部分兼容模板读操作已支持， 模板写操作推荐使用容器镜像来替代
API密钥管理teams, api-keys完全兼容OpenKruise Agents 扩展：基于团队的多租户 API 密钥管理
卷管理volumes不支持持久化卷管理待实现