文档首页/ AgentSphere/ SDK参考/ 沙箱模板及快照管理
更新时间:2026-10-27 GMT+08:00
分享

沙箱模板及快照管理

沙箱模板是沙箱实例的规格定义,描述了实例创建时的运行环境配置,包括镜像、资源规格、网络配置、存储挂载和环境变量等参数。通过模板可以将环境配置标准化和复用,避免每次创建实例时重复配置。

模板定义完成后您可以对其进行构建,构建过程中系统会运行沙箱镜像并执行配置好的启动命令,待环境就绪后,将整个沙箱的文件系统、内存和进程状态保存为构建产物,即模板快照。

前提条件

以下示例均基于E2B SDK,请确保已完成配置本地E2B SDK执行环境。

创建沙箱模板

您可以使用Template.build_in_background方法异步创建沙箱模板和快照。

from e2b import Template, wait_for_port
template = (
    Template()
    .from_image("<your_image>")
    .set_start_cmd(
        "python3 -m http.server 8081",
        wait_for_port(8081),
    )
)
build = Template.build_in_background(
    template,
    name="template-test",
    arch="x86_64",
    description="test",
    api_headers={
        "X-User-Project-ID":"user-project-id-02",
        "X-Project-ID":"project-id-02",
    },
    memory_mb=4096,
    gateway_id="gateway-id-02",
    network_configuration={
        "networkMode": "networkModePrivate",
        "targetProjectId": "targetProjectId-02",
        "targetVpcId": "targetVpcId-02",
        "targetSubnetId": "targetSubnetId-02",
    },
    invoke={
        "protocol": "HTTP",
        "port": 49984,
    },
    env_vars={"FOO_1": "bar-1"},
    first_invoke_cmd=["/bin/sh", "-c", "echo build-ready-1"],
    agencies={
        "runtimeAgency": "my-agency-1",
    },
    liveness_probe={
        "probeHandler": {
            "httpGet": {
                "path": "/health-1",
                "protocol": "HTTP",
                "port": 49983,
            },
        },
        "probeConfig": {
            "initialDelaySeconds": 3,
            "timeoutSeconds": 6,
            "periodSeconds": 4,
            "failureThreshold": 12,
            "enabled": True,
        },
    },
    observability={
        "logs": {
            "enableStdLogs": True,
        },
    },
    session_storage_config={
        "mountDir": "mountDir-1",
    },
    storage_config={
        "obsMounts": [
            {
                "bucket": "bucket-1",
                "bucketPath": "bucketPath-1",
                "mountDir": "mountDir-1",
                "readOnly": True,
            }
        ],
        "sfsTurboMounts": [
            {
                "sfsTurboId": "sfsTurboId-1",
                "shareRoot": "shareRoot-1",
                "sharePath": "sharePath-1",
                "mountDir": "mountDir-1",
                "readOnly": False,
                "withSessionCredential": True,
            }
        ],
    },
)
print(f"template build started: {build}")
status= Template.get_build_status(build)
print(f"get build status: {status}")

参数

是否必选

说明

template

必选

沙箱模板对象,用于定义沙箱实例的基础配置(基础镜像、构建步骤、启动命令等)。通过Template().from_image(...)创建。

name

必选

模板名称,构建成功后以该名称标识模板。

arch

必选

沙箱运行架构,如x86_64。需与基础镜像架构匹配,影响构建产物和运行时兼容性。

description

可选

模板描述信息,用于说明该模板的用途、环境内容等,便于管理和检索。

api_headers

可选

自定义API请求头,以字典传递。示例中的X-User-Project-ID、X-Project-ID用于华为云多租户/项目隔离场景,标明沙箱归属的用户项目与项目ID,确保资源创建在正确的项目空间下。

timeout

可选

沙箱实例的超时时间(秒)。超时后沙箱自动终止,防止资源长期占用。

api_key

必选

访问AgentSphere服务的API Key,用于身份认证与权限控制。

memory_mb

必选

沙箱分配的内存量(MB)。例如4096表示4GB内存。

gateway_id

必选

华为云AgentSphere网关实例ID,指定沙箱网络流量经过的网关实例,用于网络隔离与访问控制。

network_configuration

必选

沙箱网络配置,控制沙箱连接的网络模式与所属网络资源。

networkModePrivate表示私有网络模式;targetProjectId/targetVpcId/targetSubnetId 指定沙箱接入的目标项目、VPC 与子网,实现跨项目组网或按需网络接入。

invoke

可选

沙箱被调用(invoke)时的协议与端口配置。

protocol: HTTP表示通过HTTP协议访问;port为对外暴露的服务端口(如49984),供外部/EnvD调用沙箱内服务。

env_vars

可选

沙箱环境变量,以字典形式传入(如FOO_1: bar-1),沙箱内进程启动后可直接读取,用于注入配置、密钥或运行参数。

first_invoke_cmd

可选

首次调用(invoke)时在沙箱内执行的命令。示例/bin/sh -c "echo build-ready-1"用于沙箱就绪后执行一次初始化/验证命令,返回执行结果确认环境可用。

agencies

可选

沙箱运行时使用的委托/代理(Agency)配置。runtimeAgency指定华为云IAM委托名称,使沙箱内进程可通过该委托获得临时凭证访问其他云服务(如OBS、SFS等)。

liveness_probe

可选

沙箱存活探针,用于检测沙箱内主服务是否健康可用,不健康时触发重启/重建。

  • probeHandler.httpGet:定义HTTP探测方式
    • path:探测路径
    • protocol:HTTP协议
    • port:探测端口
  • probeConfig:定义探测策略
    • initialDelaySeconds:启动后延迟探测秒数
    • timeoutSeconds:单次探测超时
    • periodSeconds:探测周期
    • failureThreshold:连续失败多少次判定不健康
    • enabled:是否启用探针

observability

可选

沙箱可观测性配置,控制日志/监控采集。logs.enableStdLogs为true时收集沙箱标准输出日志(stdout/stderr),便于排查沙箱内运行问题。

session_storage_config

可选

会话级存储配置。mountDir指定会话存储挂载到沙箱内的目录路径,用于在会话期间保存临时/中间数据,会话结束可回收。

storage_config

可选

沙箱持久化存储配置,挂载外部存储到沙箱。

  • obsMounts:OBS对象存储挂载数组
    • bucket:桶名
    • bucketPath:桶内路径
    • mountDir:挂载到沙箱内路径
    • readOnly:是否只读
  • sfsTurboMounts:SFS Turbo文件系统挂载数组
    • sfsTurboId:文件系统 ID
    • shareRoot/sharePath:共享根/共享路径
    • mountDir:挂载目录
    • readOnly:是否只读
    • withSessionCredential:是否注入会话临时凭证访问该文件系统

cpu_count

可选

沙箱分配的CPU核数,默认2。

tags

可选

为模板构建附加其他标签,便于多版本管理。

skip_cache

可选

为True时强制全量重建,忽略构建缓存,用于排查缓存导致的构建问题。

删除沙箱模板

您可以使用Template.delete_build删除沙箱模板。

Template.delete_build(build.template_id, build.build_id)
print("template build deleted")

参数

说明

template_id

沙箱模板ID,可在控制台页面查看。

build_id

模板构建后的快照ID,可在控制台页面查看。

相关文档