容器服务
容器服务
文档指南
请输入
- 文档首页
容器服务弹性容器实例 VCI用户指南VCI Agent Sandbox基于 E2B 协议管理SDK 开发指南
复制全文
下载 pdfSDK 开发指南
文档反馈
问问助手本文主要介绍使用 E2B 协议管理 VCI Agent Sandbox 的 SDK 开发指南。
E2B 兼容概况
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 生命周期
请求 body 参数
返回参数
SandboxInfo
使用示例
def create_sandbox(template):
sbx = Sandbox.create(template=template, secure=True)
print("created sandbox_id=", sbx.sandbox_id)
return sbx
返回参数
SandboxInfo
使用示例
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 参数
返回参数
SandboxInfo
使用示例
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_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
使用示例
def create_snapshot(sandbox_id: str) -> None:
sbx = Sandbox.connect(sandbox_id)
snap_shot_info = sbx.create_snapshot()
请求 path 参数
使用示例
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)
监控管理
返回参数
SandboxMetrics
使用示例
def metrics_operation(sbx):
res = sbx.get_metrics()
print(res)
最近更新时间：2026.08.05 15:29:52
这个页面对您有帮助吗？
有用
有用
无用
无用