Agent Runtime 创建自定义沙箱（基于代码解释器沙箱镜像）

三、1.1 前置条件

·本地已安装 Docker。

·已完成容器镜像服务（个人版）的初始化操作，详情请参见 容器镜像服务个人版快速入门。

·若使用容器镜像服务企业版，请参见 容器镜像服务企业版快速入门。

注意：说明：

注意：下文示例均以你的镜像仓库地址 ccr.ccs.tencentyun.com/example/code:v1 为例，请在实际操作中替换为你的真实地址。

四、1.2 构建镜像

1. 首先在你的计算机的目录下创建 Dockerfile。

2. 参考以下内容编写 Dockerfile。

# 腾讯云Agent沙箱 代码解释器沙箱镜像FROM ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest# 安装你想要的依赖RUN pip install aiohttp

3. 在项目根目录下执行以下命令构建镜像：

docker build -t ccr.ccs.tencentyun.com/example/code:v1 . –platform=linux/amd64

参数说明：

·-t：指定镜像的完整标签（格式：仓库地址/镜像名:版本）。

·.：使用当前目录下的 Dockerfile。

·–platform=linux/amd64：指定目标平台为 linux/amd64。

注意：当前只支持使用 linux/amd64 目标平台的镜像。

五、1.3 推送镜像

在项目根目录下执行以下命令：

docker push ccr.ccs.tencentyun.com/example/code:v1

六、1.4（可选）推送已有镜像

假设已有镜像的地址为 ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest，可按以下步骤操作：

1. 先拉取该镜像：

docker pull ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest

2. 然后给该镜像打上要推送到的镜像仓库的 tag：

docker tag ccr.ccs.tencentyun.com/ags-image/sandbox-code:latest ccr.ccs.tencentyun.com/example/code:v1

3. 推送该镜像到镜像仓库：

docker push ccr.ccs.tencentyun.com/example/code:v1

七、二、创建角色

1. 登录腾讯云 访问管理控制台，选择左侧导航中的角色。

2. 单击新建角色，选择角色载体：腾讯云产品服务。如下：

3. 创建以 Agent Runtime 为角色载体的角色。

3.1 选择 Agent Runtime 作为角色载体。

3.2 若使用容器镜像服务个人版（CCR），授予 CCR 权限 。

如果你使用企业版，则授予 TCR 权限。

注意：上述操作授予了 TCR/CCR 的全部权限，如果你需要精细化管控，请查阅 访问控制相关文档，以下为 TCR 的最小权限集示例：

注意：你可以根据需要修改你要授权的资源，在 resource 处将 * 替换为对应镜像仓库的资源六段式。

注意：{ "statement": [ { "action": [ "tcr:CreateInstanceToken", "tcr:DescribeImages", "tcr:DescribeInstances", "tcr:DescribeInternalEndpoints", "tcr:DescribeNamespaces", "tcr:DescribeRepositories", "tcr:DescribeApplicationTokenPersonal", "tcr:DescribeImagePersonal", "tcr:DescribeImageFilterPersonal", "tcr:DescribeRepositoryOwnerPersonal", "tcr:DescribeNamespacePersonal", "tcr:DescribeRepositoryFilterPersonal", "tcr:PullRepository*" ], "effect": "allow", "resource": "*" } ], "version": "2.0"}

注意：

3.3 配置角色标签：按需设置角色标签，如无需要可直接进入下一步。

3.4 设置角色名称：

注意：说明：

注意：请记住此处你填写的角色名称，该名称将在后续步骤中使用。

4. 单击完成。

八、三、授予账号 PassRole 权限

1. 登录腾讯云 访问管理控制台，选择左侧导航中的角色。

2. 选择你刚创建的角色进入详情页。

3. 复制角色的 RoleArn。

4. 访问腾讯云 访问管理控制台的策略页面，单击新建自定义策略。

4.1 选择按策略语法创建。如下：

4.2 选择空白模板。

4.3 填写策略内容。

注意：请将 qcs::cam::uin/**********:roleName/ags-ccr-full 替换为步骤3复制的 RoleArn。

{ "version": "2.0", "statement": [ { "action": [ "cam:PassRole" ], "effect": "allow", "resource": [ "qcs::cam::uin/**********:roleName/ags-ccr-full" ] } ]}

5. 进入访问管理控制台的 用户列表，为目标用户或用户组授予策略。

九、四、通过控制台创建自定义沙箱

1. 访问腾讯云 Agent Runtime 的 沙箱（原自定义沙箱），单击新建沙箱工具。如下：

2. 在创建沙箱工具页面：

2.1 配置工具名称和已创建的 CAM 角色。

2.2 配置镜像和启动命令。

注意：代码解释器沙箱镜像使用 S6-Overlay 作为启动管理系统，其中 /init 为 S6 的启动入口命令，默认启动参数 sleep infinity 用于保持沙箱持续运行。

注意：如果你需要运行自定义程序，可以将 sleep infinity 替换为你的应用启动命令，例如：python /app/app.py。具体参数填写方式请参考下方注意事项：

注意：1. 启动命令必须为 /init，以确保代码解释器沙箱的内置功能正常加载。

注意：2. 每个启动参数需分别填写在独立的输入框中。例如，默认参数应填写为：

注意：3. 默认工作目录（Workdir）为根目录 /，且不可修改；默认运行用户为 root，且不可修改。

2.3 配置端口和资源规格。

注意：说明：

注意：49999 是使用代码解释器沙箱 run_code 功能所需的端口，49983 是使用代码解释器 commands.run、files.write 和 files.read 所需的端口。

注意：请根据你的需求选择资源规格，代码解释器原生功能需要至少 1 核 CPU 和 1 GiB 内存。

2.4 配置探针和网络策略。

注意：说明：

注意：此处使用代码解释器沙箱 envd 服务的 /health 端口做探针，可以保证沙箱启动后功能可用。

2.5 按需配置其他参数如文件系统挂载、环境变量等。

注意：如果你在启动命令处 /init 后面启动了你的应用程序，且想要让其读取环境变量，请在环境变量中加入 S6_KEEP_ENV=1。

3. 单击确定完成创建。

十一、最小可用配置

以下示例展示了基于代码解释器镜像创建自定义沙箱工具的最小可用配置：

{ "ToolName": "my-code-sandbox", "ToolType": "custom", "Description": "基于代码解释器镜像的自定义沙箱", "DefaultTimeout": "5m", "NetworkConfiguration": { "NetworkMode": "PUBLIC" }, "RoleArn": "qcs::cam::uin/<你的主账号UIN>:roleName/<你创建的角色名>", "CustomConfiguration": { "Image": "ccr.ccs.tencentyun.com/<你的命名空间>/<你的镜像>:<版本>", "Command": [ "/init" ], "Args": [ "sleep", "infinity" ], "Ports": [ { "Name": "run-code", "Port": 49999, "Protocol": "TCP" }, { "Name": "envd", "Port": 49983, "Protocol": "TCP" } ], "Resources": { "CPU": "2", "Memory": "1Gi" }, "Probe": { "HttpGet": { "Path": "/health", "Port": 49983 }, "ReadyTimeoutMs": 30000, "ProbeTimeoutMs": 1000, "ProbePeriodMs": 1000, "SuccessThreshold": 1, "FailureThreshold": 30 } }}

注意：说明：

注意：上述示例显式传入了 Command 和 Args 以确保行为明确。在冷启动场景下，如果你的 Dockerfile 未覆盖 ENTRYPOINT 和 CMD，这两个字段可以省略，运行时会自动使用镜像内置的 /init sleep infinity。

十二、必填参数

十三、启动命令和参数

沙箱实例有两种启动方式，对镜像配置的要求不同：

冷启动会执行镜像中的启动命令，快照启动不会重新执行镜像启动流程，而是直接恢复冻结现场。

Command 对应 Docker 的 ENTRYPOINT，Args 对应 Docker 的 CMD。冷启动时，不传则使用镜像内定义的 ENTRYPOINT 和 CMD。

是否需要填写 Command 和 Args 取决于你的 Dockerfile 写法：

注意：如果你的 Dockerfile 覆盖了 ENTRYPOINT，例如 ENTRYPOINT ["python", "app.py"]，必须通过 Command 传入 ["/init"] 将 S6 入口补回。否则代码解释器的 run_code、commands.run、files.read 和 files.write 等内置功能将无法使用。

注意：每个启动参数需作为数组中的独立元素传入，例如 "Args": ["sleep", "infinity"]，不要写成 "Args": ["sleep infinity"]。

十四、快照启动约束

如果你的沙箱需要支持快照启动，请确保 Dockerfile 满足以下约束：

兼容快照启动的 Dockerfile 示例如下：

FROM ccr.ccs.tencentyun.com/ags-image/sandbox-code:latestRUN pip install aiohttp pandas

不兼容快照启动的 Dockerfile 示例如下：

FROM ccr.ccs.tencentyun.com/ags-image/sandbox-code:latestRUN pip install aiohttp pandasWORKDIR /appUSER appuserENV MY_VAR=hello

注意：如果需要支持快照启动，请勿在 Dockerfile 中修改 USER 和 WORKDIR，并将所有自定义环境变量通过 API 的 Env 参数配置。

十五、端口配置

代码解释器沙箱至少需要声明以下两个端口：

系统默认开放 8080 端口，无需在 Ports 中声明。除 8080 端口外，最多可额外声明 3 个端口。代码解释器沙箱的 49999 和 49983 已占用 2 个额外端口名额，最多还可以追加 1 个自定义端口。

如果你的自定义应用需要额外暴露端口，例如 Web 服务，可在数组中追加端口：

"Ports": [ { "Name": "run-code", "Port": 49999, "Protocol": "TCP" }, { "Name": "envd", "Port": 49983, "Protocol": "TCP" }, { "Name": "my-web", "Port": 3000, "Protocol": "TCP" }]

注意：上述配置已用满 3 个额外端口名额。如需开放更多端口，请 提交工单 联系平台支持。

十六、资源规格

可选资源规格参考如下：

十七、健康检查

推荐使用代码解释器 run-code 服务的 /health 端点作为健康检查探针。

十八、环境变量

默认无需配置环境变量。如果你通过启动参数运行自定义程序，且该程序需要读取环境变量，请添加 S6_KEEP_ENV=1：

"Env": [ { "Name": "S6_KEEP_ENV", "Value": "1" }, { "Name": "MY_APP_CONFIG", "Value": "your-value" }]

注意：代码解释器沙箱使用 S6-Overlay 管理进程，默认不会将宿主环境变量传递给子进程。设置 S6_KEEP_ENV=1 后，你定义的环境变量可被自定义程序读取。快照启动时不会读取 Dockerfile 中的 ENV 指令，所有自定义环境变量必须通过 API 的 Env 参数显式传入。

十九、其他可选配置

21、最简配置

Dockerfile 只加依赖、未修改 ENTRYPOINT 和 CMD 时，Command 和 Args 可省略：

{ "ToolName": "code-sandbox-basic", "ToolType": "custom", "NetworkConfiguration": { "NetworkMode": "PUBLIC" }, "RoleArn": "qcs::cam::uin/100000001:roleName/ags-ccr-full", "CustomConfiguration": { "Image": "ccr.ccs.tencentyun.com/my-namespace/my-code:v1", "Ports": [ { "Name": "run-code", "Port": 49999, "Protocol": "TCP" }, { "Name": "envd", "Port": 49983, "Protocol": "TCP" } ], "Resources": { "CPU": "2", "Memory": "1Gi" }, "Probe": { "HttpGet": { "Path": "/health", "Port": 49983 }, "ReadyTimeoutMs": 30000, "ProbeTimeoutMs": 1000, "ProbePeriodMs": 1000, "SuccessThreshold": 1, "FailureThreshold": 30 } }}

22、运行自定义 Web 应用

通过 Args 覆盖 CMD，让 S6 启动后运行 Flask 服务：

{ "ToolName": "code-sandbox-web", "ToolType": "custom", "DefaultTimeout": "1h", "NetworkConfiguration": { "NetworkMode": "PUBLIC" }, "RoleArn": "qcs::cam::uin/100000001:roleName/ags-ccr-full", "CustomConfiguration": { "Image": "ccr.ccs.tencentyun.com/my-namespace/my-code-web:v1", "Args": [ "python", "/app/server.py" ], "Env": [ { "Name": "S6_KEEP_ENV", "Value": "1" }, { "Name": "FLASK_PORT", "Value": "8080" } ], "Ports": [ { "Name": "run-code", "Port": 49999, "Protocol": "TCP" }, { "Name": "envd", "Port": 49983, "Protocol": "TCP" }, { "Name": "flask-web", "Port": 8080, "Protocol": "TCP" } ], "Resources": { "CPU": "2", "Memory": "2Gi" }, "Probe": { "HttpGet": { "Path": "/health", "Port": 49983 }, "ReadyTimeoutMs": 30000, "ProbeTimeoutMs": 1000, "ProbePeriodMs": 1000, "SuccessThreshold": 1, "FailureThreshold": 30 } }}

23、高配数据分析场景

如果需要运行数据分析或模型推理任务，可提高资源规格并延长超时时间：

{ "ToolName": "code-sandbox-data", "ToolType": "custom", "DefaultTimeout": "24h", "Description": "数据分析沙箱", "NetworkConfiguration": { "NetworkMode": "PUBLIC" }, "RoleArn": "qcs::cam::uin/100000001:roleName/ags-ccr-full", "CustomConfiguration": { "Image": "ccr.ccs.tencentyun.com/my-namespace/my-code-data:v1", "Ports": [ { "Name": "run-code", "Port": 49999, "Protocol": "TCP" }, { "Name": "envd", "Port": 49983, "Protocol": "TCP" } ], "Resources": { "CPU": "4", "Memory": "4Gi" }, "Probe": { "HttpGet": { "Path": "/health", "Port": 49983 }, "ReadyTimeoutMs": 30000, "ProbeTimeoutMs": 1000, "ProbePeriodMs": 1000, "SuccessThreshold": 1, "FailureThreshold": 30 } }, "Tags": [ { "Key": "scenario", "Value": "data-analysis" } ]}

24、默认值速查表

25、六、创建并访问沙箱实例

创建沙箱工具后，可通过 CreateSandboxInstance API 创建具体的沙箱实例。示例如下：

{ "ToolId": "sdt-xxxx", "Timeout": "30m"}

ToolId 为创建沙箱工具时返回的 ID。Timeout 可选，不填则使用沙箱工具的 DefaultTimeout。

创建成功后，接口返回 InstanceId，例如 sbi-abcd1234。

26、通过 E2B 兼容 SDK 访问

Agent Runtime 沙箱兼容 E2B API。你可以使用 e2b-code-interpreter 或 @e2b/code-interpreter 包操作沙箱。

安装 Python SDK：

pip install e2b-code-interpreter

安装 TypeScript SDK：

npm install @e2b/code-interpreter

Python 示例：

from e2b_code_interpreter import Sandboxsbx = Sandbox(template="my-code-sandbox")execution = sbx.run_code('print("Hello from sandbox!")')print(execution.logs)result = sbx.commands.run("ls -la /")print(result.stdout)sbx.files.write("/tmp/data.txt", "Hello World")content = sbx.files.read("/tmp/data.txt")print(content)sbx.kill()

TypeScript 示例：

import { Sandbox } from '@e2b/code-interpreter'const sbx = await Sandbox.create('my-code-sandbox')const execution = await sbx.runCode('print("Hello from sandbox!")')console.log(execution.logs)const result = await sbx.commands.run('ls -la /')console.log(result.stdout)await sbx.files.write('/tmp/data.txt', 'Hello World')const content = await sbx.files.read('/tmp/data.txt')console.log(content)await sbx.kill()

连接到已有沙箱实例的 Python 示例：

from e2b_code_interpreter import Sandboxsbx = Sandbox.connect(sandbox_id="sbi-abcd1234")execution = sbx.run_code("import sys; print(sys.version)")print(execution.logs)

27、通过 HTTP 直连访问

每个沙箱实例的每个开放端口都有一个独立的公网访问 URL，格式如下：

https://{port}-{instanceId}.{region}.tencentags.com

例如，实例 ID 为 sbi-abcd1234、部署在 ap-shanghai 地域时，访问地址如下：

默认情况下，访问沙箱实例需要在 HTTP 请求头中携带访问令牌：

X-Access-Token: <实例的 Access Token>

Access Token 在创建沙箱实例时返回。如果不需要 Token 认证，可在创建实例时指定 AuthMode 为 none。

注意：只有在 Ports 中声明过的端口以及默认 8080 端口才可通过公网访问。未声明的端口无法从外部连通。

29、冷启动下 Command 和 Args 什么时候可以不填？

只要你的 Dockerfile 没有覆盖 ENTRYPOINT，Command 和 Args 都可以不填。运行时会自动使用镜像内置的 ENTRYPOINT ["/init"] 和 CMD ["sleep", "infinity"]。最常见的只加依赖场景，例如 RUN pip install …，不需要填写这两个字段。

30、冷启动下什么情况下必须填写 Command？

当你的 Dockerfile 使用 ENTRYPOINT 指令覆盖了基础镜像入口时，例如 ENTRYPOINT ["python", "app.py"]，必须通过 Command 传入 ["/init"] 将 S6 入口补回。否则代码解释器的内置服务不会启动，run_code、commands.run、files.write 等功能将不可用。

31、如果只想使用代码解释器沙箱镜像的原始功能，需要填写 CustomConfiguration 吗？

不需要。如果你不需要自定义镜像，可以直接创建 ToolType 为 code-interpreter 的沙箱工具，而不是创建 ToolType 为 custom 的沙箱工具。此时无需传入 CustomConfiguration，系统会使用内置的默认配置。详情请参见 创建沙箱工具。

32、资源规格最低要求是多少？

代码解释器原生功能至少需要 1 核 CPU 和 1 GiB 内存（1Gi）。推荐使用 2 核 CPU，以获得更流畅的代码执行体验。

33、自定义程序读取不到环境变量怎么办？

请在环境变量中添加 S6_KEEP_ENV=1。S6-Overlay 默认不向子进程传递环境变量，该配置会保留你定义的环境变量。如果使用快照启动，Dockerfile 中的 ENV 指令不生效，所有环境变量必须通过 API 的 Env 参数显式传入。

34、快照启动对 Dockerfile 有什么约束？

快照恢复启动时，进程状态由快照中冻结的现场决定。Dockerfile 必须满足以下约束：不修改 USER，保持 root；不修改 WORKDIR，保持 /；自定义环境变量必须通过 API 的 Env 参数配置，不能仅依赖 Dockerfile 的 ENV 指令。Command 和 Args 在快照启动时不生效。

35、端口数量有什么限制？

系统默认开放 8080 端口，无需声明。除 8080 端口外，最多可额外声明 3 个端口。代码解释器沙箱的 49999 和 49983 各占用 1 个额外端口名额，因此最多还可以追加 1 个自定义端口。

36、8080 端口需要在 Ports 中声明吗？

不需要。8080 端口由系统默认开放，不占用额外端口配额。如果你的自定义 Web 服务监听 8080 端口，无需在 Ports 数组中声明即可通过公网访问。

37、相关文档

·创建沙箱工具

·创建沙箱工具 API 文档

·数据结构 API 文档