配置沙箱模板和实例
一体化智能体运行与协同平台（AgentWorks）的沙箱为智能体提供隔离的命令、文件和代码执行环境。任务可以使用平台已准备的运行环境完成时，选择沙箱；已有独立远程工具服务时，使用 MCP；需要由接入业务系统执行企业操作时，使用用户工具包。开始前确认租户已有可用规格和环境；完成关联后，通过代表性输入、沙箱运行记录和 Trace 验证真实执行结果。
沙箱模板保存 沙箱模板启动类型、资源规格、环境配置、环境变量和工具审批配置；实例是智能体实例实际使用的沙箱资源。工具审批配置决定沙箱工具调用是否进入审批流程，智能体模板中的审批处理规则只处理已经进入该流程的调用。
沙箱从平台准备到智能体运行跨越三个阶段：
管理员控制可用规格和环境，构建者只能在租户已获得的范围内选择。选择沙箱模板时，创建智能体实例会准备专属沙箱实例；选择现有沙箱实例时，智能体实例连接固定资源。
确认使用方式和租户前提
在创建沙箱资源前，先确认任务需要的执行方式、租户可用的规格和环境，以及模板启动类型所表达的隔离方式。
区分沙箱和用户工具包
沙箱通过自己的插件向智能体提供命令、文件和执行工具。用户工具包则只描述由接入业务系统执行的工具，并通过中断取得结果。
在同一个智能体模板中同时添加沙箱和用户工具包，不会让沙箱自动执行用户工具。需要在隔离环境中完成任务时，直接为智能体模板配置沙箱并使用沙箱提供的工具；需要由业务系统调用企业 API 时，使用用户工具包；已有独立工具服务时，使用 MCP。
确认租户已有规格和环境
警告
仅限 AgentWorks 管理控制台
创建或修改沙箱规格和沙箱环境，以及为租户分配沙箱规格，只能在独立的 AgentWorks 管理控制台 完成。AgentWorks 控制台只能选择已经分配给当前租户的规格和环境；没有合适选项时，请联系管理员。
普通用户创建沙箱模板时，只能选择平台管理员已经开放给租户的沙箱规格和环境配置。
管理员在 AgentWorks 管理控制台维护：
- 沙箱规格管理：沙箱类型（Docker 或 VM）、启动类型（冷启动 或 预热启动）、Sandbox Class、CPU、内存、磁盘、运行超时、空闲回收，以及 带宽限制、出站访问控制和域名访问控制。
- 沙箱环境管理：镜像地址、内部工作目录和外部工作目录等运行环境。
- 租户详情的 沙箱规格 中的 配置沙箱规格。
该页面中的 环境变量和启动参数显示为 暂不支持，因此不能在此修改。需要不同配置时，请选择管理员已准备的其他环境，或联系管理员提供符合要求的环境。
理解“沙箱模板启动类型”
在用户控制台的 沙箱模板启动类型 中选择：
- Docker 容器
- Virtual Machine
该选项用于选择执行隔离类型。冷启动或预热启动由管理员在沙箱规格中配置。
创建沙箱资源
根据沙箱是否需要随智能体实例独立创建，选择创建模板、直接创建实例，或从模板预先创建实例。
以下入口仅在租户已启用沙箱能力时可用。按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。
创建沙箱模板
打开新建沙箱模板页面。
也可从左侧导航进入 沙箱管理，选择 沙箱模板，再选择 新建沙箱模板。
填写 名称和描述。
选择 Docker 容器 或 Virtual Machine。
在 资源规格 和 环境配置 中选择已开放的项目。
在 环境变量 中配置模板变量。
只把需要因智能体实例而变化的环境变量标记为 可配置。
在 工具审批配置 中设置审批要求。需要使用模板或渠道用户的审批处理规则时，应开启审批；关闭后，沙箱工具调用直接执行，不检查这些规则。
选择 创建沙箱模板。
模板适合每个智能体实例需要相同运行基线但不同环境变量或独立沙箱的场景。
直接创建沙箱实例
如果多个智能体实例可以共享一个固定沙箱配置，或者只需要一次性资源，可以直接创建沙箱实例：
打开新建沙箱实例页面。
也可从左侧导航进入 沙箱管理，选择 实例，再选择 创建实例。
选择类型、规格和环境，填写环境变量，并创建实例。
直接实例表单提供类型、规格、环境和环境变量，但不定义后续实例参数模板。
直接绑定已有沙箱实例时，智能体实例使用该沙箱已经具备的环境、命令和文件。通过沙箱模板创建专属沙箱时，新沙箱使用模板提供的配置。无论采用哪种方式，把技能组添加到同一个智能体模板都不会自动把 Skill 文件放入沙箱。
从模板创建实例
从模板创建时：
- 选择沙箱模板。
- 输入 实例名称和 描述。
- 填写模板开放的参数。
- 检查只读的规格和环境。
- 选择 创建实例。
如果沙箱应随智能体实例动态创建，把沙箱模板添加到智能体模板，而不是提前手动创建所有沙箱实例。
将沙箱接入智能体
沙箱资源创建后，还需要关联到智能体模板，并确认执行任务所需的命令、文件、运行时和依赖已经在环境中准备就绪。
将沙箱添加到智能体模板
- 创建或编辑智能体模板，打开 插件配置。
- 单击 添加插件。
- 选择 沙箱 - 模板 或 沙箱 - 实例，再选择目标沙箱模板或实例。
- 按需设置模板开放参数，然后保存智能体模板。
- 在智能体模板详情页的 插件 页签中确认沙箱类型、名称和资源 ID。
- 创建或更新智能体实例。
创建沙箱模板或沙箱实例后，还需要在智能体模板的 插件配置 中选择对应沙箱。创建或更新智能体实例后，再通过实际命令验证执行环境。
准备沙箱执行内容
沙箱只执行其环境中可用的命令和文件。任务依赖特定脚本、运行时或系统命令时：
- 选择已经包含所需命令和依赖的环境。
- 配置正确的工作目录和环境变量。
- 把沙箱模板或实例添加到智能体模板。
- 创建或更新智能体实例。
- 先运行一个只读、可预测的测试命令，再运行真实任务。
Skill 可以说明何时以及如何执行某项任务，但 Skill 资源不会自动成为沙箱文件。不要把 Skill ZIP 当作沙箱镜像或依赖安装包。任务需要执行脚本时，应通过沙箱环境准备所需文件、运行时和依赖，并把 Skill 激活、资源读取和沙箱执行分别作为检查点。
验证和约束沙箱运行
上线前，应同时验证实际执行路径和限制是否生效，并使用运行记录定位网络、资源、权限或启动问题。
限制沙箱网络和资源
平台管理员可以在规格中配置带宽、私网地址出站控制、DNS 允许或拒绝列表、超时和空闲回收。生产规格应按最小权限开放网络，并为长任务设置合理超时。
这些控制属于规格。普通用户不能在每个沙箱模板中任意扩大管理员分配的资源或网络权限。
查看执行记录
在 沙箱运行记录 中查看执行历史和结果。排查时同时检查：
- 智能体实例是否运行。
- 沙箱实例和规格是否可用。
- 环境变量是否按实例参数生成。
- 网络策略是否允许目标地址。
- 工具审批配置 是否让工具调用在执行前进入审批流程。
测试沙箱执行
把沙箱模板或实例添加到测试智能体，创建或更新智能体实例后，运行一个只读、可预测的测试命令。确认：
- 沙箱实例使用预期规格和环境。
- 智能体实例的 Playground 可以使用沙箱命令或文件工具。沙箱实例已经生成，不等于运行时已经取得这些工具。
- 环境变量按模板参数生成。
- 工作目录和镜像内所需命令存在。
- 网络只允许测试所需目标。
- 运行记录显示成功、耗时和预期输出。
需要为沙箱工具配置审批处理规则时，先开启 工具审批配置，再在沙箱实例详情中加载工具列表并复制实际工具名称。该列表只显示工具名称和描述；需要按参数值缩小范围时，先保留人工审批，通过一次低风险测试在 Trace 中核对实际参数，或查阅该工具的公开说明。无法确认参数结构时，不要猜测参数名或创建宽泛允许规则。参见找到工具名称和参数名。
如果智能体模板还关联了技能组，应在 Trace 中另行确认 Skill 激活和资源读取。沙箱运行记录只证明沙箱工具的实际执行，不证明 Skill 已经生效；Skill 资源读取也不证明对应文件已存在于沙箱。
再执行一个匹配模板拒绝规则的确认型调用，确认工具没有执行；另行执行一个会被网络策略拒绝的测试，确认不可绕过的运行限制同样生效。
处理超时、网络和启动失败
- 启动慢：确认管理员规格是冷启动还是预热启动，并检查资源是否可用。
- 命令超时：比较任务时长、规格运行超时和智能体实例调用超时，不要只扩大其中一个值。
- 域名无法解析：检查规格的 DNS 允许和拒绝列表，拒绝列表优先。
- 私网地址不可达：检查 RFC1918 出站限制和例外 CIDR。
- 镜像或命令不存在：检查环境镜像、工作目录和镜像版本。
- 没有可选规格或环境：让管理员确认资源已分配给当前租户且类型匹配。
不要通过永久放开所有网络或取消所有超时来解决单次失败。
安全修改或删除沙箱
修改共享沙箱实例会影响所有引用它的智能体模板和智能体实例。需要分阶段变更时，创建替代实例或模板，在测试智能体实例中验证后再切换生产引用。
删除沙箱模板后，请在实例列表中检查并分别处理相关沙箱实例。删除沙箱实例前，先移除智能体模板和智能体实例引用，保留必要运行记录，并确认实例工作目录中没有仍需留存的数据。
仍被模板或实例引用的规格和环境不能删除。请先迁移所有引用，再执行删除。