agent\-sandbox 组件是 AI Agent 安全沙箱管理组件。本文介绍 agent\-sandbox 组件的功能、核心资源、安装配置和后续验证方式。 ## 组件概述 agent\-sandbox 组件是 VCI Agent Sandbox 业务场景的核心组件，该组件基于 Kubernetes 社区 SIG Agent Sandbox 实现，扩展了沙箱快照、暂停、恢复等能力，并兼容 E2B API 设计。安装组件后，您可以在集群中管理 AI Agent 运行所需的沙箱生命周期。启用 E2B Server 后，组件会额外提供 E2B 兼容 API 的控制面和数据面能力。安装 agent\-sandbox 组件后，系统会根据配置创建控制器、E2B Server 相关工作负载及访问凭证资源。下表仅列出从当前资料中可确认的核心资源，如果您在安装时调整资源名称或 E2B Server 开关等配置，请以实际安装结果为准。 |**资源名称** |**资源类型** |**说明** | |---|---|---| |agent\-sandbox\-controller |Deployment |承载组件控制器能力，用于调谐 Sandbox、SandboxClaim、SandboxWarmPool、SandboxTemplate 等资源，并处理沙箱生命周期。 | |agent\-sandbox\-control\-plane |Deployment / Service |启用 E2B Server 后创建，提供 E2B 兼容 API 的控制面服务，默认服务端口为 8081。 | |agent\-sandbox\-data\-plane |Deployment / Service |启用 E2B Server 后创建，提供 E2B 兼容 API 的数据面服务，默认服务端口为 8080。 | |e2b\-key\-store |Secret |开启 Control\-Plane 鉴权且未手动配置管理员密钥时，用于保存自动生成的管理员密钥。 | ## 组件版本 agent\-sandbox 组件提供了关于组件的历史发布记录、各版本新增特性及优化说明等信息。详情请参见 [组件发布记录](https://docs.volcengine.com/docs/6460/2626764)。 ## 安装组件 1. 登录 [容器服务控制台](https://console.volcengine.com/vke)。 2. 在左侧导航栏中，选择 **集群**，单击目标集群名称，进入集群管理页面。 3. 在集群管理页面左侧导航栏中，选择 **组件管理**，并选择 **Sandbox** 页签。 4. 将鼠标移动到组件卡片上，单击 **部署**，配置组件相关参数。 |参数 |描述 | |---|---| |**部署配置** || |部署形态 |仅已安装了 vci\-virtual\-kubelet 组件的集群显示该参数。部署组件的节点类型，有如下两种方式：

* **云服务器部署**：表示在集群中的云服务器节点（Node）上部署该组件。

* **弹性容器部署**：表示在集群中的弹性容器实例（VCI），即虚拟节点（VirtualNode）上部署该组件。在弹性容器实例上部署组件，会产生费用，详细的费用说明，请参见 [弹性容器实例产品计费](https://www.volcengine.com/docs/6460/76912)。 | |**访问凭证** || |Access Key |输入您火山引擎账号的 API 访问秘钥（AK、SK），为 agent\-sandbox 组件相关的资源部署授权。获取方式，请参见 [API 密钥（Access Key 与 API Key）](https://docs.volcengine.com/docs/6257/64983)。

注意

请确保您的火山引擎账号（含 IAM 用户），已配置 VKEFullAccess 系统预设策略，或者自定义策略中包含如下最小集合授权项（Action），才能保证当前账号通过 VCI Agent Sandbox 访问和操作资源：

ExecContainerImageCommitment

DescribeContainerImageCommitments

CreateSnapshot

DeleteSnapshot

DescribeSnapshots

CreateImageCache

ListImageCaches

为 IAM 用户授权相关操作，请参见 IAM 权限。

| |Secret Key || |**Controller 配置** || |启用扩展能力 |是否启用 agent\-sandbox 组件的扩展功能。

* 开启：启用 Snapshot、Commit、SandboxWarmPool、SandboxTemplate、SandboxClaim 等扩展功能。强烈建议保持默认开启状态。

* 关闭：关闭扩展功能。 | |默认创建 Service |Sandbox CR 上不配置是否创建 Service 时，通过控制器的该参数配置判断是否创建 Service。

* 开启：创建 Service，便于集群内资源访问 Sandbox。

* 关闭：不创建 Service，后续您需要自行配置访问 Sandbox 方式。 | |副本数 |组件 Pod 副本数。设置多副本时，需配合开启 **启用 Leader 选举** 按钮。 | |Sandbox 并发 worker 数 |Sandbox 控制器最大并发调谐（Reconcile）数。

* 取值范围：正整数。

* 默认值：32，建议保持默认值。 | |SandboxClaim 并发 worker 数 |SandboxClaim 控制器最大并发调谐数。

* 取值范围：正整数。

* 默认值：32，建议保持默认值。 | |SandboxWarmPool 并发 worker 数 |SandboxWarmPool 控制器最大并发调谐数。

* 取值范围：正整数。

* 默认值：32，建议保持默认值。 | |SandboxTemplate 并发 worker 数 |SandboxTemplate 控制器最大并发调谐数。

* 取值范围：正整数。

* 默认值：32，建议保持默认值。 | |Kube API QPS |调用 Kubernetes API 的 QPS 限流参数，用于防止管理组件时对 API Server 造成过大压力。

* 取值范围：正整数。

* 默认值：100，建议保持默认值。 | |Kube API Burst |调用 Kubernetes API 的突发请求上限，用于防止管理组件时对 API Server 造成过大压力。

* 取值范围：正整数。

* 默认值：200，建议保持默认值。 | |启用 Leader 选举 |开启后，表示启用 Leader 选举机制，解决资源竞争问题。

注意

多副本部署时，此处必须开启，以此避免多个副本同时执行业务逻辑引发资源竞争问题。

| |附加启动参数 |传递额外启动标志（Flag），例如传递 Zap 日志参数等未单独抽象的 Flag。 | |节点标签选择 |开启后，可设置节点标签，组件的核心工作负载会被调度到带有该指定标签的节点上。 | |节点污点调度 |开启后，可设置污点容忍值，组件的核心工作负载允许被调度到带有指定污点的节点。 | |节点强制调度 |开启后，可设置节点选择标签的策略，组件的核心工作负载会根据调度策略，强制调度到满足要求的节点。 | |资源配置 |组件控制器自身 CPU/内存的请求与上限。建议您结合实际使用规模，适当调整控制器的规格配置。 | |**E2B 配置** || |启用 E2B Server |开启后，表示启用 E2B。您还需要配置下方所有参数。 | |服务账号名称 |服务账号（ServiceAccount）名称，建议保持默认值。如需自定义，请遵循 Kubernetes 命名格式要求。 | |E2B 服务域名后缀 |E2B 服务域名后缀，用于生成 E2B 控制面（Control\-Plane）和数据面（Data\-Plane）的访问域名，建议保持默认值。

* **Control\-Plane**：E2B API 控制面组件，一个无状态的管控组件，是 E2B 协议的执行入口，用来处理 Sandbox 的创删等 API 请求。

* **Data\-Plane**：E2B API 数据面组件，一个无状态的组件，将代码指令或命令执行等操作的 API 请求转发给 Sandbox。

注意

部署应用模板后，在 VKE 集群内配置 ALB Ingress 规则，将e2b.com指向控制面负载，*.e2b.com指向数据面负载。详细操作，请参见通过 Ingress 暴露 E2B 服务。

如果对性能有要求，推荐通过 APIG 进行数据面转发，则无需将*.e2b.com指向数据面负载。详细操作，请参见基于 API 网关访问 VCI Agent Sandbox。

注意

使用 v2.25.0 及以上版本 E2B SDK 时，此处建议采用e2b_xxxxx格式的 E2B API Key。

不设置时，会随机生成一个 API Key 并保存在`agent-sandbox-system`命名空间下名为`e2b-key-store`的 Secret 里。 | |Control\-Plane 名称 |Control\-Plane 对应组件名称。建议保持默认值。如需自定义，请遵循 Kubernetes 命名格式要求。 | |Control\-Plane 服务名称 |Control\-Plane 服务名称。建议保持默认值。如需自定义，请遵循 Kubernetes 命名格式要求。 | |Control\-Plane 副本数 |Control\-Plane 副本数。可根据文件大小、文件/代码操作频率适当调整副本数。 | |空闲连接超时 |空闲连接超时时间。

* 格式为：Go duration 字符串。

* 取值范围：正整数。

* 默认值：600s，建议保持默认值。 | |响应写入超时 |响应写入超时时间。

* 格式为：Go duration 字符串。

* 取值范围：正整数。

* 默认值：600s，过小可能导致长请求提前中断。建议保持默认值。 | |Sandbox 生命周期超时 |Sandbox 生命周期超时时间。

* 格式为：Go duration 字符串。

* 取值范围：正整数。

* 默认值：600s，过小可能导致创建 Sandbox 或修改 Sandbox 的接口在调用完成前提前退出。建议保持默认值。 | |Rest Client QPS |访问 Kubernetes API 的 QPS 限流。

* 取值范围：正整数。

* 默认值：50，建议保持默认值。 | |Rest Client Burst |访问 Kubernetes API 的突发请求上限。

* 取值范围：正整数。

* 默认值：100，建议保持默认值。 | |Control\-Plane 服务端口 |Control\-Plane 服务端口。建议保持默认值：8081。 | |Control\-Plane 资源配置 |Control\-Plane CPU/内存的请求与上限。可根据文件大小、文件/代码操作频率适当调整。 | |Data\-Plane 名称 |Data\-Plane 组件名称，建议保持默认值。如需自定义，请遵循 Kubernetes 命名格式要求。 | |Data\-Plane 服务名称 |Data\-Plane 服务名称。建议保持默认值。如需自定义，请遵循 Kubernetes 命名格式要求。 | |Data\-Plane 副本数 |Data\-Plane 副本数。可根据文件大小、文件/代码操作频率适当调整副本数。 | |Data\-Plane 服务端口 |Data\-Plane 服务端口。建议保持默认值：8080。 | |Data\-Plane 资源配置 |Data\-Plane CPU/内存的请求与上限。可根据文件大小、文件/代码操作频率适当调整。 | 5. 单击 **确认**，完成配置。 ## 升级组件组件会不定期发布新版本以提供新特性或修复已知问题。当组件卡片提示有可用更新时，建议您及时进行升级。为确保业务平稳过渡，升级前请尽量安排在业务低峰期执行操作。关于升级的操作步骤和注意事项，请参见 [升级组件](https://www.volcengine.com/docs/6460/159826)。 ## 相关文档 * [VCI Agent Sandbox 功能介绍](https://docs.volcengine.com/docs/6460/2275548) * [VCI Agent Sandbox 生命周期管理](https://docs.volcengine.com/docs/6460/2230011) * [基于 E2B 协议管理 VCI Agent Sandbox](https://docs.volcengine.com/docs/6460/2479107)