使用E2B SDK接入Agent Sandbox

背景信息

ACS Agent Sandbox兼容E2B SDK，您可以使用E2B SDK创建、管理和连接Sandbox实例。Agent Sandbox基于OpenKruise Agents实现E2B协议兼容，支持两种E2B协议：

• 原生协议（Native Protocol）：每个Sandbox按端口使用独立子域名，访问格式为<PORT>-<SANDBOX_ID>.DOMAIN，API入口为api.DOMAIN。需要泛域名DNS解析和TLS证书，适合生产环境。

• 私有协议（Private Protocol）：所有Sandbox共享同一域名，通过URL路径区分，访问格式为DOMAIN/kruise/<SANDBOX_ID>/<PORT>，API入口为DOMAIN/kruise/api。仅需单域名，简化网络配置并降低证书成本。

安装组件

1. 登录容器计算服务控制台，在左侧导航栏选择集群列表。

2. 在集群列表页面，单击目标集群名称，然后在左侧导航栏，选择组件管理。

3. 安装 Ingress Controller 和 Sandbox 相关组件。

   1. 安装Ingress Controller组件。

      安装ACS支持的任一Ingress Controller组件，用于从集群外部访问sandbox-manager服务。后续步骤以安装ALB Ingress Controller为例，新建一个公网类型的ALB实例。

   2. 安装ack-agent-sandbox-controller组件。

      首次安装需要先授权AliyunCSManagedAgentSandboxRole角色访问您的云资源，参数可先按照默认设置，如有额外并发需求，可再提升对应资源规格。

      关于该组件功能的详细说明，请参见ack-agent-sandbox-controller。

   3. 安装ack-sandbox-manager组件。

      1. 准备E2B域名。

         准备域名、域名解析和申请证书的详细操作，请参见应用于生产环境。

      2. 配置组件参数。

         修改className为alb（即安装Ingress Controller组件中自动创建的IngressClass），修改domain为实际域名，修改adminApiKey为自定义API Key，其他配置保持默认。组件安装完成后会在sandbox-system命名空间中创建一个名为sandbox-manager的路由。

         详细参数说明

         配置项	参数	说明
         sandboxManager	replicaCount	sandbox-manager 实例个数，默认值为 3。
         E2B	domain	E2B域名，请参考准备E2B域名。
         	Enable E2B_API_KEY verification	是否开启 API_KEY 鉴权，默认开启。
         	adminApiKey	开启鉴权后，首次安装时通过该配置项来指定最初的 Key。请替换为自定义的API Key。
         Controller	logLevel	controller日志等级，默认为 1。
         	resources.requests.cpu	controller CPU资源请求，默认为 2。
         	resources.requests.memory	controller 内存资源请求，默认为 4Gi。
         Proxy	resources.requests.cpu	proxy CPU资源请求，默认为 2。
         	resources.requests.memory	proxy 内存资源请求，默认为 4Gi。
         Ingress	className	集群中已配置的 IngressClass 名称，如 alb、mse。

      3. 若使用ALB Ingress Controller，还需同时为ALB实例和Ingress新增HTTPS:443监听配置。

         更新AlbConfig，为ALB实例新增HTTPS:443监听。

         1. 在左侧导航栏，选择工作负载 > 自定义资源。在资源对象浏览器页签中，搜索AlbConfig，然后单击搜索结果。

         2. 在AlbConfig资源对象列表中，找到目标资源alb，单击其右侧操作列下的YAML 编辑。

         3. 新增spec.listeners.port: 443和spec.listeners.protocol: HTTPS字段，然后单击确定。

            spec:
              config:
                addressAllocatedMode: Fixed
                addressType: Internet
                zoneMappings:
                  - vSwitchId: vsw-xxx
                  - vSwitchId: vsw-xxx
              listeners:
                - port: 80
                  protocol: HTTP
                - port: 443
                  protocol: HTTPS

         更新Ingress，关联HTTPS:443监听。

         1. 在左侧导航栏，选择网络 > 路由。在sandbox-manager路由右侧操作栏中，单击更新。

         2. 添加以下配置，单击确定。

            • 注解：alb.ingress.kubernetes.io/listen-ports: [{"HTTP": 80}, {"HTTPS": 443}]

步骤一：创建预热池

1. 单击左侧导航栏自定义资源，选择资源定义（CustomResourceDefinition）页签，单击使用YAML创建资源。

2. 使用以下 YAML 创建 SandboxSet 资源。ack-sandbox-manager 会自动监听并识别该资源，同步初始化名为 code-interpreter 的沙箱模板配置。

   启用动态存储挂载功能，需要为容器开放特权容器（Privileged Container）和宿主机路径（hostPath，/var/run/csi）的容器安全验证，可以提交工单放开限制，但由此带来的安全风险需要用户承担一定责任，相关机制请参见安全责任共担模型。

   apiVersion: agents.kruise.io/v1alpha1
   kind: SandboxSet
   metadata:
     name: code-interpreter
     namespace: default
   spec:
     runtimes:
     - name: csi           # 支持CSI挂载能力，新建的Sandbox会被注入对应的Sidecar
     - name: agent-runtime # 注入envd等环境管理工具
     replicas: 4
     template:
       metadata:
         labels:
           alibabacloud.com/acs: "true"
           alibabacloud.com/compute-class: agent-sandbox # Agent Sandbox 实例类型 
           alibabacloud.com/compute-qos: default # 算力质量 default/best-effort
       spec:
         automountServiceAccountToken: false
         containers:
         - image: registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/code-interpreter:v1.6 # 替换成实际集群所在的地域
           imagePullPolicy: IfNotPresent
           name: sandbox
           resources:
             limits:
               cpu: "1"
               memory: 1Gi
             requests:
               cpu: "1"
               memory: 1Gi
               ephemeral-storage: 30Gi
         terminationGracePeriodSeconds: 30

   code-interpreter镜像使用说明

   • 镜像拉取：registry-cn-zhangjiakou-vpc.ack.aliyuncs.com/acs/code-interpreter镜像是 ACS 基于 e2b-code-interpreter 项目制作的示例镜像，兼容 E2B 客户端的run_code接口。为了提高镜像拉取速度可将镜像地址中的地域修改为实际的地域名字，或去除-vpc通过公网拉取。

     重要

     该镜像仅用于演示和测试环境，不建议在生产环境使用。如需在生产环境中部署，请务必进行必要的安全加固、性能优化及功能增强，以满足实际业务的安全性与稳定性要求。

   • 使用自定义镜像：如需使用 E2B code-interpreter（直接使用或作为 base 镜像），推荐选择 ACS 提供的版本化镜像。ACS 不保证运行时与 E2B 官方 latest 镜像的兼容性。如需要使用自定义镜像，请确保镜像满足以下条件：

     1. 包含 cp、mv、mkdir 等基础指令。

     2. 包含 bash 且可执行文件位于/bin/bash。

     使用自定义镜像时，E2B 的run_code方法暂时无法使用。

3. 单击左侧导航栏容器组，选择对应的命名空间，查看已创建的code-interpreter Sandbox。

   可通过kubectl get sbs命令查看 SandboxSet 资源，其中AVAILABLE表示已就绪的 Sandbox 数量。

步骤二：安装E2B SDK

E2B SDK目前支持 Python、Java、Go 等多种编程语言。本文以 Python 语言为例进行说明，如需了解其他语言的详细集成指南，请参考e2b-client。

1. 安装Python环境。

2. 安装E2B Python SDK。Agent Sandbox仅支持低于v2.25.0的E2B SDK版本。

   pip install "e2b-code-interpreter==2.7.0" "e2b==2.24.0"

步骤三：配置E2B_DOMAIN

E2B_DOMAIN是E2B SDK连接sandbox-manager的域名配置，客户端与组件配置必须一致。

域名的注册与解析请参考云解析DNS。

# 设置E2B_DOMAIN，与组件domain参数保持一致
export E2B_DOMAIN=<YOUR_E2B_DOMAIN>
# 设置E2B_API_KEY，与组件adminApiKey参数保持一致
export E2B_API_KEY=<YOUR_API_KEY>

（可选）步骤四：安装证书

如果您需要通过 HTTPS 访问 sandbox-manager，需要安装 TLS 证书。建议使用受信任的CA证书。各种证书申请及配置方式，请参考以下文档：

• （推荐）方式一： 使用 cert-manager 管理证书

• 方式二：使用自签证书

• 方式三：采用正式证书（以 Let's Encrypt 为例）

检查 Secret 是否成功创建以及类型是否正确（应为 kubernetes.io/tls）：

kubectl get secret sandbox-manager-tls -n sandbox-system

步骤五：选择集成方式连接Sandbox

根据您的网络环境和需求，选择以下集成方式之一连接Sandbox。

以下示例code-interpreter 为占位名，需替换为您实际创建的 SandboxSet 名称。

• 方式一：集群外通过原生协议访问：生产环境推荐，需泛域名和TLS证书。

• 方式二：集群外通过私有协议访问（HTTPS）：单域名即可，降低部署门槛。

• 方式三：端口转发到本地调试：适合本地开发调试。

E2B API兼容性说明

相关文档

• 创建Agent Sandbox

• E2B Client