容器服务
容器服务
容器服务
文档指南
请输入
容器服务 VKE
产品动态
Kubernetes 版本发布记录
组件发布记录
监控组件
DNS 组件
GPU 组件
Sandbox 组件
安全公告
产品公告
历史公告
用户指南
集群
节点池
授权
网络
容器网络
服务（Service）
路由（Ingress）
APIG Ingress
ALB Ingress
自定义转发规则配置示例
CLB Ingress
Nginx Ingress
Gateway API
工作负载
存储
数据管理中心（DMC）
对象存储（TOS）
FSX 访问方式
文件存储（NAS）
FSX 访问方式
弹性文件存储（EFS）
文件存储（vePFS）
FSX 访问方式
vePFS Client 访问方式
NFS 访问方式
大数据文件存储（CloudFS）
弹性伸缩
工作负载弹性伸缩
事件驱动伸缩（KEDA）
组件管理
网络组件
监控组件
DNS 组件
GPU 组件
Sandbox 组件
异构计算
调度管理
可观测性
基础观测
诊断与巡检
最佳实践
网络
可观测性
安全合规
API 参考
集群管理
节点池管理
组件管理
机型镜像管理
云原生观测
巡检诊断
弹性容器实例
附录
开发指南
常见问题
通用 FAQ
集群 FAQ
集群管理
集群升级
节点与节点池 FAQ
授权 FAQ
工作负载 FAQ
服务与路由 FAQ
存储 FAQ
弹性伸缩 FAQ
可观测性 FAQ
配额 FAQ
组件 FAQ
容器镜像 FAQ
AI 云原生
推理套件
Helm 模板 AI 应用
Deepseek 实践
Qwen 实践
最佳实践
MiniMax 模型部署
Qwen 模型部署
弹性容器实例 VCI
最新动态
用户指南
虚拟节点
VKE 集群使用虚拟节点
自建/跨云集群使用虚拟节点
创建 VCI 实例
VCI Agent Sandbox
安全合规
- 文档首页
容器服务弹性容器实例 VCI用户指南VCI Agent Sandbox基于 E2B 协议管理SDK 开发指南
复制全文
下载 pdfSDK 开发指南
文档反馈
问问助手本文主要介绍使用 E2B 协议管理 VCI Agent Sandbox 的 SDK 开发指南。
E2B 兼容概况
分类 | API | 说明 | 兼容性 | 兼容性说明 |
分类 | API | 说明 | 兼容性 | 兼容性说明 |
Sandbox 生命周期 | create | 创建 VCI Agent Sandbox。 | 部分兼容 | 不支持网络访问控制、原地变配、自动暂停。 |
Sandbox 生命周期 | get_info | 获取 VCI Agent Sandbox 实例信息。 | 完全兼容 | 无 |
Sandbox 生命周期 | list | 列出所有 VCI Agent Sandbox 信息。 | 完全兼容 | 无 |
Sandbox 生命周期 | delete | 删除 VCI Agent Sandbox 实例。 | 完全兼容 | 无 |
Sandbox 生命周期 | connect | 连接 VCI Agent Sandbox 实例。 | 完全兼容 | 无 |
Sandbox 生命周期 | pause | 暂停 VCI Agent Sandbox 实例。该接口为异步接口，接口调用成功时，Sandbox 对应的底层 Pod 成功回收， 但快照仍在创建中。 | 完全兼容 | 无 |
Sandbox 生命周期 | resume | 恢复 VCI Agent Sandbox 实例，自动基于最近一次暂停时生成的可写层快照恢复数据。 | 完全兼容 | 无 |
文件系统 | write | 主容器需要运行e2b-code-interpreter组件。可在 Template 的initcontainer中查看e2b-code-interpreter组件的定义。 | 完全兼容 | 除了在 Template 中的initcontainer字段下定义，也可通过注解agent.sandbox.io/enable-envd-injection: "true"实现，VCI 将自动注入envd程序。 |
文件操作 | read | | 完全兼容 | |
代码执行 | run_code | | 完全兼容 | |
命令执行 | commands.run | | 完全兼容 | |
API Key 管理 | - | 由于 E2B code interpreter SDK 不包含 API Key 管理能力，通常通过 E2B Web 控制台、E2B CLI 或 HTTP 方式操作。VCI Agent Sandbox 主要提供 HTTP 调用方式，包括 POST、DELETE、GET。 | 不涉及 | 无 |
Template 管理 | post_templates | 在构建完整的 SandboxTemplate 结构后创建模板。 | 完全兼容 | 无 |
| requests.delete | 删除模板。原生 E2B SDK 中无该接口，建议按需通过 API 操作模板。 | 不涉及 | 无 |
| requests.patch | 更新模板。原生 E2B SDK 中无该接口，建议按需通过 API 操作模板。 | 不涉及 | 无 |
| requests.get | 获取单个模板详情。原生 E2B SDK 中无该接口，建议按需通过 API 操作模板。 | 不涉及 | 无 |
快照管理 | create_snapshot | 创建快照。 | 完全兼容 | 无 |
| requests.delete | 删除快照。 | 不兼容 | 无 |
| list_snapshot | 查询快照列表，仅返回已制作完成且可用的快照。 | 完全兼容 | 无 |
监控管理 | get_metrics | 获取 Sandbox 的运行监控数据。 | 部分兼容 | 不支持指定起止时间。 |
E2B SDK 说明
E2B 官网提供多种 SDK 接入，其中包括e2b和e2b_code_interpreter等接入方式。本文场景中推荐您使用e2b_code_interpreter，该方式预装了可用于数据分析的 Python 库。
pip install e2b-code-interpreter==2.4.1 e2b==2.10.2 anthropic python-dotenv
E2B 标准能力
Sandbox 生命周期
创建 Sandbox
查询 Sandbox
删除 Sandbox
暂停 Sandbox
恢复 Sandbox
请求 body 参数
参数名 | 类型 | 是否必选 | 说明 |
参数名 | 类型 | 是否必选 | 说明 |
template | string | 是 | 创建 Sandbox 时使用的 Template ID。 |
timeout | int | 否 | Sandbox 的存活时间：
|
metadata | Dict[str, str] | 否 | 需要传递给 Sandbox 的额外注解信息。 |
secure | bool | 否 | Sandbox 是否开启envd鉴权：
|
返回参数
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
SandboxInfo | Class | 包含 Sandbox 基本信息的类。子参数说明，见下方 SandboxInfo。 |
SandboxInfo
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
template_id | string | 创建 Sandbox 时使用的 Template ID。 |
sandbox_id | string | Sandbox 实例的 ID。 |
envd_version | string | 使用的envd版本。 |
_envd_access_token | string | envd的鉴权信息。 |
domain | string | E2B API 的访问域名。 |
使用示例
def create_sandbox(template):
sbx = Sandbox.create(template=template, secure=True)
print("created sandbox_id=", sbx.sandbox_id)
return sbx
返回参数
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
SandboxInfo | Class | 包含 Sandbox 基本信息的类。子参数说明，见下方 SandboxInfo。 |
SandboxInfo
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
template_id | string | 创建 Sandbox 时使用的 Template ID。 |
sandbox_id | string | Sandbox 实例的 ID。 |
envd_version | string | 使用的envd版本。 |
_envd_access_token | string | envd的鉴权信息。 |
domain | string | E2B API 的访问域名。 |
使用示例
def get_sandbox_info(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id=sandbox_id)
info = sbx.get_info()
print("sandbox_id=", info.sandbox_id)
print("template_id=", info.template_id)
print("state=", info.state)
print("started_at=", info.started_at)
print("end_at=", info.end_at)
print("metadata=", info.metadata)
使用示例
def delete_sandbox(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id=sandbox_id)
ok = sbx.kill()
print("killed:", ok)
使用示例
def pause_sandbox(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id=sandbox_id)
sbx.beta_pause()
请求 path 参数
参数名 | 类型 | 是否必选 | 说明 |
参数名 | 类型 | 是否必选 | 说明 |
sandboxId | string | 是 | Sandbox 实例的 ID。 |
返回参数
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
SandboxInfo | Class | 包含 Sandbox 基本信息的类。子参数说明，见下方 SandboxInfo。 |
SandboxInfo
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
template_id | string | 创建 Sandbox 时使用的 Template ID。 |
sandbox_id | string | Sandbox 实例的 ID。 |
envd_version | string | 使用的envd版本。 |
_envd_access_token | string | envd的鉴权信息。 |
domain | string | E2B API 的访问域名。 |
使用示例
def resume_sandbox(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id=sandbox_id)
文件系统
上传文件
下载文件
使用示例
def upload_file(sbx):
with open("./test.txt", "rb") as file:
sbx.files.write("/test.txt", file)
使用示例
def read_file(sbx):
file_content = sbx.files.read("/test.txt")
print(file_content)
代码执行
代码执行
使用示例
def run_code(sbx):
sbx.run_code("print('hello world')")
命令执行
命令执行
使用示例
def run_command(sbx):
sbx.commands.run('echo hello')
API Key 管理
VCI 提供 POST、DELETE、GET 等 HTTP 调用方式。
创建 API Key
删除 API Key
获取 API Key 列表
使用示例
# API Key 配置
API_BASE_URL = os.getenv("API_BASE_URL", "your.domain")
ADMIN_API_KEY = os.getenv("ADMIN_API_KEY", "sk-local-test-123456")
# API 请求头
headers = {
"X-API-KEY": ADMIN_API_KEY,
"Content-Type": "application/json"
}
def create_api_key(name):
"""Create a new API key"""
url = f"{API_BASE_URL}/api-keys"
payload = {"name": name}
print(f"Creating API key: {name}")
response = requests.post(url, headers=headers, json=payload)
使用示例
url = f"{API_BASE_URL}/api-keys/{key_id}"
headers = {
"X-API-KEY": ADMIN_API_KEY,
"Content-Type": "application/json"
}
response = requests.delete(url, headers=headers)
使用示例
url = f"{API_BASE_URL}/api-keys"
headers = {
"X-API-KEY": ADMIN_API_KEY,
"Content-Type": "application/json"
}
print(f"Getting API key list...")
response = requests.get(url, headers=headers)
模板（Template）管理
创建模版
删除模板
更新模板
获取单个模版详情
使用示例
from e2b.connection_config import ConnectionConfig
from e2b.api.client_sync import get_api_client
from e2b.api.client.api.templates import post_templates
from e2b.api.client.models import TemplateBuildRequest
"""
使用官方 E2B SDK 创建 SandboxTemplate
Args:
api_base_url: E2B API 服务基础地址
api_key: API 认证密钥
template_name: 模版名称
namespace: Kubernetes 命名空间（默认 default）
template_spec: 可选的模版 spec 配置
"""
# 2. 配置模版 spec
if template_spec is None:
template_spec = {
"podTemplate": {
"metadata": {
"annotations": {
"agent.sandbox.io/snapshot-max-num": "2",
"vci.vke.volcengine.com/enable-auto-create-imc": "true",
"vci.vke.volcengine.com/preferred-instance-family": "vci.u1,vci.n3i",
"vci.volcengine.com/persistent-container": "true",
"vci.volcengine.com/tls-enable": "false",
"vci.volcengine.com/usable-disk-capacity": "40",
"vke.volcengine.com/burst-to-vci": "enforce"
}
},
"spec": {
"containers": [
{
"env": [
{"name": "ENVD_DIR", "value": "/mnt/envd"},
{"name": "PORT", "value": "49999"}
],
"image": "cr-cn-guilin-boe.volces.com/vke/code-interpreter:v0.1.0",
"lifecycle": {
"postStart": {
"exec": {
"command": ["/bin/bash", "-c", "/mnt/envd/envd-run.sh"]
}
}
},
"name": "main",
"resources": {
"limits": {"cpu": "2", "memory": "4Gi"},
"requests": {"cpu": "2", "memory": "4Gi"}
},
"volumeMounts": [
{"mountPath": "/mnt/envd", "name": "envd-volume"}
]
}
],
"initContainers": [
{
"command": ["sh", "/workspace/entrypoint.sh"],
"env": [
{"name": "ENVD_DIR", "value": "/mnt/envd"},
{"name": "__IGNORE_RESOURCE__", "value": "true"}
],
"image": "helm-cr-cn-guilin-boe.cr.volces.com/vke/agent-runtime:v0.0.4",
"name": "runtime",
"restartPolicy": "Always",
"volumeMounts": [
{"mountPath": "/mnt/envd", "name": "envd-volume"}
]
}
],
"terminationGracePeriodSeconds": 1,
"volumes": [{"emptyDir": {}, "name": "envd-volume"}]
}
}
}
# 3. 构建完整的 SandboxTemplate 结构
sandbox_template = {
"apiVersion": "extensions.agents.x-k8s.io/v1alpha1",
"kind": "SandboxTemplate",
"metadata": {
"name": template_name,
"namespace": namespace
},
"spec": template_spec
}
# 4. 初始化 E2B SDK 连接配置
try:
config = ConnectionConfig(
api_key=api_key,
api_url=api_base_url
)
# 获取 API 客户端
api_client = get_api_client(
config,
require_api_key=True,
require_access_token=False
)
print(f" ✅ SDK 连接初始化成功！")
except Exception as e:
print(f" ❌ SDK 连接初始化失败: {e}")
return None
# 5. 构建 SDK 请求对象
# 必填，TemplateBuildRequest 必须传入 dockerfile 字段，即使自定义 server 未使用 dockerfile 字段，也需传入空值
build_request = TemplateBuildRequest(
dockerfile=""
)
build_request["namespace"] = namespace
build_request["sandboxTemplate"] = sandbox_template
print(f" ✅ 请求对象构建成功！")
# 6. 调用官方 SDK 接口创建模版
# 使用 sync_detailed 可以获取完整响应信息
response = post_templates.sync_detailed(
body=build_request,
client=api_client
)
使用示例
# 模版请求格式为 namespace--template-id
template_path = f"{namespace}--{template_id}"
url = f"{api_base_url}/templates/{template_path}"
headers = {
"X-API-KEY": api_key,
"Content-Type": "application/json",
}
params = {}
if owner:
params["owner"] = owner
response = requests.delete(url, headers=headers, params=params)
原生 E2B SDK 提供的更新接口，仅支持修改 Template 的公开/私有状态切换，VCI Agent Sandbox 的 E2B 管理能力支持修改 Template 的更多属性定义。
注意
- 更新模板时，请参照 创建模板 的请求入参，构造完整的请求。
- 需要修改annotations、containers相关配置时，即使仅修改其中某个字段，也需传入相应配置块下的所有信息。
使用示例
import os
import sys
from e2b.connection_config import ConnectionConfig
from e2b.api.client_sync import get_api_client
from e2b.api.client.api.templates import patch_templates_template_id
from e2b.api.client.models import TemplateUpdateRequest
"""
使用 E2B SDK 修改模板
"""
template_path = f"{namespace}--{template_id}"
# 1. 创建连接配置
config = ConnectionConfig(
api_key=api_key,
api_url=api_base_url
)
# 2. 获取 API 客户端
api_client = get_api_client(
config,
require_api_key=True,
require_access_token=False
)
# 3. 创建更新请求对象
update_request = TemplateUpdateRequest()
# 构建完整的请求 payload，与创建模版类似
# 只支持到 containers/annotations 粒度的修改，如需修改 containers 中某个字段信息，需传入 containers 下的所有字段信息
# 包含 namespace 和 sandboxTemplate 两个字段
sandbox_template = {
"apiVersion": "extensions.agents.x-k8s.io/v1alpha1",
"kind": "SandboxTemplate",
"metadata": {
"name": template_id,
"namespace": namespace
},
"spec": {
"podTemplate": {
"spec": {
"containers": [
{
"name": "main",
"image": new_image
}
]
}
}
}
}
payload = {
"namespace": namespace,
"sandboxTemplate": sandbox_template
}
# 通过 additional_properties 添加到 update_request
update_request["namespace"] = namespace
update_request["sandboxTemplate"] = sandbox_template
# 发送请求
print(f"\n🚀 发送更新请求...")
url = f"{api_base_url}/templates/{template_path}"
headers = {
"X-API-KEY": api_key,
"Content-Type": "application/json"
}
try:
response = requests.patch(url, headers=headers, json=payload)
使用示例
# 模版请求格式为 namespace--template-id
template_path = f"{namespace}--{template_id}"
url = f"{api_base_url}/templates/{template_path}"
headers = {
"X-API-KEY": api_key,
"Content-Type": "application/json",
}
response = requests.get(url, headers=headers)
返回结果
{
"templateID": "template-13ec94e0-ab32-4a26-837d-f0167ffb1004",
"public": false, // 模版不支持设置为公开/私有
"aliases": [
"template-13ec94e0-ab32-4a26-837d-f0167ffb1004"
],
"names": [
"template-13ec94e0-ab32-4a26-837d-f0167ffb1004"
],
"createdAt": "2026-05-05T14:54:28Z",
"updatedAt": "2026-05-05T14:54:28Z",
"lastSpawnedAt": null, // 不支持记录模版的最后一次使用时间
"spawnCount": 0, // 不支持获取模版的使用次数
"builds": [
{
"buildID": "a9d48185-53f6-4baf-b0d4-e273e5230c66",
"status": "ready"
}
]
}
快照管理
创建快照
删除快照
查询快照列表
返回参数
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
SandboxInfo | Class | 包含 Sandbox 基本信息的类。子参数说明，见下方 SandboxInfo。 |
SandboxInfo
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
snapshotId | string | 快照的 ID。 |
使用示例
def create_snapshot(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id)
snap_shot_info = sbx.create_snapshot()
请求 path 参数
参数名 | 类型 | 是否必选 | 说明 |
参数名 | 类型 | 是否必选 | 说明 |
sandboxId | string | 是 | Sandbox 实例的 ID。 |
使用示例
def delete_snapshot(snapshot_id: str) -> None:
"""
api_base_url: E2B API 服务基础地址
api_key: API 认证密钥
"""
url = f"{api_base_url}/snapshots/{snapshot_id}"
headers = {
"X-API-KEY": api_key,
"Content-Type": "application/json",
}
response = requests.delete(url, headers=headers)
使用示例
def list_snapshot(sandbox) -> None:
paginator = sbx.list_snapshots()
while paginator.has_next:
snapshots = paginator.next_items()
print(snapshots)
监控管理
获取监控
返回参数
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
List[SandboxMetrics] | List | 包含 Sandbox 基本信息的列表。子参数说明，见下方 SandboxMetrics。 |
SandboxMetrics
参数名 | 类型 | 说明 |
参数名 | 类型 | 说明 |
cpu_count | Integer | Sandbox 的 CPU 总核数。 |
cpu_used_pct | Float | Sandbox 的 CPU 使用率。 |
disk_total | Integer | Sandbox 的磁盘总量。 |
disk_used | Integer | Sandbox 已经使用的磁盘大小。 |
mem_total | Integer | Sandbox 的内存总量。 |
mem_used | Integer | Sandbox 已经使用的内存大小。 |
timestamp | DataTime | 指标时间戳。 |
使用示例
def metrics_operation(sbx):
res = sbx.get_metrics()
print(res)
最近更新时间：2026.08.05 15:29:52
这个页面对您有帮助吗？
有用
有用
无用
无用