配置沙箱模板和实例

在智能体开发服务平台（AgentWorks）中，沙箱让智能体在受控环境中执行命令、处理文件和运行代码。沙箱是可选能力，不是智能体实例的默认运行边界。沙箱模板保存创建沙箱时使用的设置；沙箱实例是实际运行任务的环境。多个智能体实例选择同一个沙箱实例时，会共享其中的文件、环境变量和运行状态。

选择是否使用沙箱

先根据任务需要的执行方式选择路径，再决定是否创建沙箱资源。

需要的结果	选择	执行位置或共享结果
使用模型、知识、记忆或 Skill，或者使用平台内置、远程 MCP 或调用方工具	不配置沙箱	对应的 AgentWorks 服务、MCP Server 或接入方执行工具；Skill 本身不执行命令
每个智能体实例需要自己的命令、文件或代码环境	沙箱模板	创建每个智能体实例时分别准备沙箱
多个智能体实例有意共享工作区、配置和运行状态	现有沙箱实例	所有引用方共享文件、环境变量、凭证和清理操作
每段会话或每次运行需要全新执行环境	用户工具包或远程 MCP 管理的外部环境	调用方或 MCP 服务管理创建、身份校验、复用和销毁；该环境不是 AgentWorks 沙箱

平台工具包由 AgentWorks 执行，外部 MCP 工具由 MCP Server 执行，用户工具由业务系统执行。添加这些能力不会创建或关联 AgentWorks 沙箱。需要比较工具执行位置时，参见根据任务选择能力和定义用户工具包。

选择文件系统功能、沙箱和对象存储

文件系统功能、沙箱和对象存储分别解决当前任务文件、命令执行和长期保存问题。先确定模型是否只需整理当前会话的文件、是否要运行命令，以及结果是否需要长期保存。文件系统功能的基本含义参见了解文件系统功能和工作文件。

方式	如何启用	适合	文件范围和保留方式
文件系统功能（未关联沙箱）	在智能体模板中开启 启用文件系统；新建模板默认开启	让模型通过智能体文件工具读取、整理或生成任务文件	文件按会话读写；新会话看不到上一会话创建的文件。需要跨会话保留时写入已批准的外部存储
沙箱工作目录	向智能体模板添加沙箱模板或实例；文件工具改用所关联沙箱的工作区	执行命令、代码和需要特定镜像或依赖的文件处理	使用同一沙箱资源的智能体共享工作区；保留时长以目标环境的实际配置为准
沙箱对象存储挂载	创建沙箱模板或实例时开启 存储挂载；可以单独使用，无需开启智能体模板的 启用文件系统	让沙箱访问企业自有的 S3 兼容对象存储	需要保留的写入应从对象存储控制台按完整路径重新下载并核对；并发写入前还应验证目标应用和对象存储的处理方式

在 文件系统 中开启 启用文件系统 后，模型可以使用智能体文件工具。未关联沙箱时，这些工具按会话读写文件，新会话看不到上一会话创建的文件；关联沙箱后，它们改为读写所关联沙箱的工作区。需要跨会话或运行环境保留文件时，请把文件写入已批准的外部存储。

OSS 或其他对象存储挂载由沙箱配置。访问挂载时，请把相应沙箱接入智能体，并按挂载的只读或读写设置操作。启用文件系统 只控制智能体文件工具；关闭后，沙箱命令仍可按运行环境权限创建本地文件。验证对象存储挂载时，请从对象存储控制台按完整路径重新读取测试对象。

只需要模型在同一会话中读取或整理文件时，开启文件系统即可。需要运行命令、使用特定环境或访问对象存储挂载时，再添加沙箱。选择沙箱模板时，每个智能体实例使用各自的沙箱；选择现有沙箱实例时，关联它的智能体共享工作区。分别在所选位置核对文件，并向管理员确认重启、替换或删除后的保留和清理方式。

选择沙箱模板或实例

默认选择 沙箱 - 模板：

• 选择 沙箱 - 模板 时，平台会为每个智能体实例创建一个沙箱。不同智能体实例不会共享其中的文件、挂载的 Skill 和运行状态。
• 选择 沙箱 - 实例 时，所有使用这个沙箱的智能体实例都会进入同一个工作区，共享文件、环境变量和运行状态。

只有多个智能体实例明确需要共享这些内容时，才选择现有沙箱实例；无法确认时，仍选择沙箱模板。新建会话不会创建新沙箱。需要不同 Skill、文件或凭证的智能体不要复用同一个现有沙箱实例。

确认沙箱适合当前任务

创建前，先确认两件事：任务需要在沙箱中运行命令或处理文件，并且当前租户已有可用的沙箱规格和环境。

区分沙箱和用户工具包

根据任务实际执行的位置选择能力：

• 需要在沙箱中运行命令、读写文件或执行代码时，使用沙箱。
• 需要由接入 AgentWorks 的业务系统调用企业 API 时，使用用户工具包。
• 已有独立的远程工具服务时，使用 MCP。

在同一个智能体模板中同时添加沙箱和用户工具包，不会让沙箱自动执行用户工具。这两种能力仍按各自的方式执行。

确认租户已有规格和环境

重要

仅限 AgentWorks 管理控制台

创建或修改沙箱规格和沙箱环境，以及为租户分配沙箱规格，只能在独立的 AgentWorks 管理控制台 完成。AgentWorks 控制台只能选择已经分配给当前租户的规格和环境；没有合适选项时，请联系管理员。

普通用户创建沙箱模板时，只能选择平台管理员已经开放给当前租户的规格和环境。

管理员在 AgentWorks 管理控制台中完成以下工作：

• 在 沙箱规格管理 中设置沙箱类型、CPU、内存、磁盘、超时和网络限制。
• 在 沙箱环境管理 中准备镜像和工作目录。
• 在租户详情的 沙箱规格 中选择 配置沙箱规格，把规格分配给租户。

管理端环境页面中的 环境变量和启动参数目前显示为 暂不支持。需要其他配置时，请选择管理员已准备的环境，或联系管理员。管理员可参见管理沙箱资源。

理解沙箱模板启动类型

在用户控制台的 沙箱模板启动类型 中选择：

• Docker 容器
• Virtual Machine

该选项用于选择新沙箱的隔离类型：Docker 容器或虚拟机。冷启动或预热启动由管理员在沙箱规格中设置。

上线前确认启动、回收、保留和费用

Docker 容器或 Virtual Machine 表示隔离类型。上线前，请另行向平台管理员确认沙箱是否常驻、首次执行需要等待多久、空闲后是否回收、工作目录能保留多久，以及空闲期间是否计费。

沙箱在第一次工具调用时创建或分配运行环境。同一沙箱资源 ID 的运行环境仍可用时，后续工具调用可能继续使用该环境。沙箱隔离按资源划分，而不是按 AgentWorks 会话、调用任务或调用方划分；需要隔离文件、进程或凭证时，请使用不同的沙箱资源。

需要可预测的任务期限时，请让平台管理员提供目标环境实际生效的运行超时和空闲回收配置，并在应用层设置截止时间、取消处理和幂等恢复。规格页面中的数值仅供配置参考；资源释放和安全清理仍应使用组织规定的明确流程。

对于 Docker 沙箱，容器销毁时会自动移除容器，写在容器内部可写层中的文件随之消失。外部工作目录和对象存储挂载在清理时会被卸载，外部文件或对象继续由对应存储管理。判断运行环境销毁后的文件结果时，先确认路径属于容器内部、外部工作目录还是对象存储挂载。

为生产任务选择规格前，请让平台管理员确认：

• 冷启动或预热方式，以及首次执行的预期等待时间。
• 单次运行超时、空闲回收阈值和回收后的启动行为。
• 工作目录和进程能否跨空闲回收、重新启动或维护继续保留。
• 计费单位，以及启动中、运行中、空闲和预热资源分别如何计费。

费用规则以目标环境的计费说明或服务合同为准。需要长期保留的文件和结果应写入管理员确认的外部存储，并从存储端重新读取以验证结果。管理员应按说明沙箱如何启动、回收和计费说明规格中的磁盘、工作目录、启动、回收和计费方式。

警告

按实际环境配置管理任务期限

向平台管理员确认实际生效的运行超时和空闲回收时间，并在应用层设置任务截止时间。数据保留、锁释放和安全清理请使用各自的明确机制；一次观察到的回收时间只用于本次排查。

创建沙箱资源

沙箱实例可以直接选择规格和环境进行创建，不需要先创建沙箱模板。沙箱规格和环境仍需由管理员提前提供。

根据沙箱是否需要随智能体实例分别创建，选择创建模板、直接创建实例，或从模板预先创建实例。

以下入口仅在租户已启用沙箱能力时可用。按钮会在新标签页打开控制台。若先进入登录页，控制台目前不会在登录后自动返回目标页面；请登录后返回本文，再次选择按钮。

创建沙箱模板

1. 打开新建沙箱模板页面。

   创建沙箱模板

   也可从左侧导航进入 沙箱管理，选择 沙箱模板，再选择 新建沙箱模板。

2. 填写 名称和描述。

3. 选择 Docker 容器 或 Virtual Machine。

4. 在 资源规格 和 环境配置 中选择已开放的项目。

5. 在 环境变量 中配置模板变量。

6. 只把需要因智能体实例而变化的环境变量标记为 可配置。

7. 可选：按挂载对象存储配置企业自有存储。

8. 选择 创建沙箱模板。

当多个智能体实例需要相同的运行设置，但要分别使用自己的文件、环境变量和运行状态时，请选择沙箱模板。

仅在共享相同文件时创建沙箱实例

只有所有使用这个沙箱的智能体实例都可以共享相同文件、Skill、凭证和运行状态时，才使用此路径。任一项无法确认时，请创建沙箱模板。

确认共享沙箱实例的影响

选择现有沙箱实例后，所有使用这个沙箱的智能体实例都会进入同一个工作区。一个智能体写入的文件可能被其他智能体看到或修改；重启、清理和资源占用也会相互影响。文件能保留多久、运行环境是否会持续存在，取决于管理员提供的环境。

共享内容	用户可能遇到的问题
文件和输出	看到其他用户或任务创建的文件，或者自己的文件被覆盖、修改或删除
Skill、脚本和依赖	看到非预期的 Skill 集合，或者受到其他任务所做脚本和依赖变更的影响
执行状态和资源	并发任务争用 CPU、内存或磁盘；共享环境中留下的进程或中间状态影响后续任务
环境变量和凭证	使用这个沙箱的任务使用相同配置，写入其中的凭证不会按智能体分开
更新、重启和清理	一个智能体的变更、重启或清理中断其他任务，或者删除其他任务仍需使用的状态

同一租户中具有相应权限的用户，可以在不同智能体模板中选择同一个现有沙箱实例。由不同用户创建智能体，不会让沙箱内容自动分开。

注意

不支持不同 Skill 集合共享同一个沙箱实例

不支持让需要不同 Skill 集合的智能体复用同一个现有沙箱实例。共享沙箱只有一个 /skills 视图，不会按智能体合并或切换 Skill 文件。

例如，智能体 A 使用 Skill 1–3 并先初始化共享沙箱后，智能体 B 即使配置了 Skill 4–6，也可能仍只看到 Skill 1–3。

请选择 沙箱 - 模板，让每个智能体实例获得自己的沙箱。只有所有智能体实例都可以共享相同文件、Skill 集合和运行状态时，才选择 沙箱 - 实例。

直接创建或选择现有沙箱实例前，确认以下条件全部满足：

• 所有智能体使用相同的 Skill 集合和版本；需要执行 Skill 文件时，这些文件已经放入共享沙箱。
• 所有使用者都可以看到同一组输入文件、工作文件和输出。
• 所有智能体可以使用相同的环境变量和凭证。
• 修改文件、重启或清理沙箱可以同时影响所有智能体。
• 团队已经记录哪些智能体使用这个沙箱，以及由谁负责变更、数据保留和清理。

任一项不满足或无法确认时，不要创建共享沙箱实例；请改为创建沙箱模板。

创建沙箱实例

通过共享检查后：

1. 打开新建沙箱实例页面。

   创建沙箱实例

   也可从左侧导航进入 沙箱管理，选择 实例，再选择 创建实例。

2. 选择类型、规格和环境，填写环境变量，并创建实例。

直接创建实例时，可以设置类型、规格、环境和环境变量，但不能把这些设置保存为可供后续实例填写参数的模板。

直接绑定已有沙箱实例时，智能体使用该沙箱中已有的环境、命令和文件。所有使用这个沙箱的智能体也会共用环境变量和对象存储挂载，并一起受到后续变更和清理的影响。工具是否自动拒绝、自动批准或进入人工审批，由各智能体模板的工具权限决定。绑定前，请记录当前和计划使用这个沙箱的智能体。

• 使用沙箱模板时，新沙箱采用模板中的设置。如果智能体模板还关联了技能组，平台会把所选版本的 Skill 文件以只读方式挂载到新沙箱的 /skills 目录。
• 直接绑定已有沙箱实例时，平台不会自动挂载该智能体的 Skill 文件。智能体只能使用沙箱中已经准备的文件。

两种方式都不会自动执行脚本或安装依赖。

从模板创建实例

从模板创建时：

1. 选择沙箱模板。
2. 输入 实例名称和 描述。
3. 填写模板开放的参数。
4. 检查只读的规格和环境。
5. 选择 创建实例。

如果沙箱应随智能体实例动态创建，把沙箱模板添加到智能体模板，而不是提前手动创建所有沙箱实例。

预先从模板创建的沙箱实例，后续通过 沙箱 - 实例 关联时仍属于共享资源，也必须满足共享实例检查。

挂载对象存储

创建沙箱模板或实例时，可以展开 存储挂载，把企业自有的 S3 兼容对象存储映射到沙箱本地目录。AgentWorks 控制台支持阿里云 OSS 和火山引擎 TOS 凭证。

配置前准备：

• 取得把目标 Bucket 或指定子目录接入 AgentWorks 的许可，并确认允许读取或写入的准确范围。
• 创建只包含本次任务所需权限的对象存储凭证。只读任务不要授予写入或删除权限。
• 在授权范围内准备一个内容已知且不含敏感信息的读取测试对象。
• 需要读写时，另行准备一个可清理的测试目录或唯一对象名，并确定获准的清理方式。不要使用生产对象测试写入、覆盖或删除。
• 确认对象的版本、生命周期、备份、恢复、访问审计和费用由哪个存储所有者管理。

任一条件不满足时，先停止配置并让存储所有者补齐权限、测试数据或恢复方案；不要使用权限更大的共享凭证绕过准备工作。

1. 在 凭证管理 的 对象存储凭证 页签预先创建凭证，或者在存储挂载中选择新建凭证。新建的凭证会进入凭证管理列表供后续复用。
2. 在沙箱模板或实例表单中开启 存储挂载。
3. 选择一个对象存储凭证。在 AgentWorks 控制台的同一个沙箱表单中，所有挂载点共用这一凭证。
4. 为每个挂载点填写 Bucket、Bucket 子目录和沙箱内的本地目录；按需添加备注。
5. 保留默认的 只读，除非任务确实需要写入并已经验证最小权限、覆盖风险和并发行为。需要写入时改为 读写。
6. 在 AgentWorks 控制台中最多添加 10 个挂载点，然后保存。保存前平台会使用所选凭证预检所有 Bucket；失败时根据页面给出的原因修正凭证、区域、Endpoint、Bucket 或网络访问。

AgentWorks 控制台会自动为本地目录补齐开头的 /，最终保存为绝对路径。不能使用 /、/tmp、/skills 等系统或平台保留路径；在控制台中，多个挂载点的本地目录不能相同，也不能互为父子目录。Bucket 名称不能填写 URL 或包含 /；Bucket 子目录不能包含 .. 或连续斜杠。

保存挂载后，把该沙箱添加到智能体模板，创建或更新智能体实例，再从 Playground 或 Invoke API 按下一节验证读取和写入。沙箱详情页中的 加载工具只用于查看沙箱提供的工具，不能代替对象存储挂载验证。对象存储挂载由沙箱配置，开启 启用文件系统不会创建挂载。

验证对象存储挂载

先在非生产沙箱中验证，再让生产智能体使用挂载：

1. 在沙箱中列出挂载目录，读取准备好的非敏感测试对象，并将内容与已知值比较。预期结果是能够找到并完整读取该对象。
2. 对默认的 只读 挂载，在准备好的测试目录中尝试创建一个新对象。预期结果是写入被拒绝，并且 Bucket 中没有新增对象。
3. 只有任务明确需要写入时，才改用 读写。在准备好的测试目录中创建一个名称唯一、内容可识别的临时对象，并在当前沙箱中读取和核对内容。随后使用对象存储控制台或组织批准的客户端，按 Bucket、子目录和完整对象名重新列出并读取该对象；无法使用这些工具时，创建不复用原工作目录的全新替代沙箱，挂载同一子目录并读取同一对象。读取成功且内容一致后，再把该对象记为已经持久化。确认路径和对象名仅属于本次测试后，按获准方式保留或清理该对象，并确认原有对象未被修改；凭证未获删除权限时，由存储所有者处理该测试对象，不要扩大凭证权限。
4. 在沙箱运行记录和智能体实例的 Trace 中核对测试结果、目标沙箱和挂载目录。

当前沙箱中的读回结果、Trace 和沙箱运行记录用于核对本次工具调用。对象是否已经持久化，请以第 3 步中对象存储端或全新替代沙箱的读取结果为准。

出现以下结果时停止接入真实任务，并按对应路径恢复：

结果	停止条件和恢复操作
保存前的 Bucket 预检失败	不要创建或更新沙箱。按页面提示核对存储类型、区域、访问地址、Bucket、凭证权限和网络访问；修正后重新预检。
挂载已保存，但无法读取已知测试对象	不要扩大权限或改为读写。先核对沙箱资源、挂载目录、Bucket 子目录和测试对象名，再由存储所有者确认凭证的读取范围。
只读挂载成功写入	立即停止让智能体使用该沙箱，不要写入真实数据。确认已保存只读设置且测试使用的是目标沙箱；仍可写入时，保留运行记录并联系管理员处理。
读写挂载无法创建临时对象，或者外部存储中找不到新对象	把写入视为失败，不要接入生产写入，也不要修改已有对象。保留目标沙箱、Trace、运行记录和完整对象名，恢复到上一个已验证的只读挂载或配置，修正权限和路径后用新的临时对象重新验证。
无法确认临时对象的准确路径或归属	不要执行批量删除。记录测试时使用的 Bucket、子目录和唯一对象名，由存储所有者只清理确认属于本次测试的对象。

危险

从对象存储或新沙箱核对后再确认写入成功

写入后，请从对象存储控制台按完整对象路径重新读取文件，或者使用全新替代沙箱读取同一对象。读取成功且内容一致后，再确认写入成功。两种方式都找不到对象时，把本次写入视为失败，停止后续业务步骤，不要用同一对象名覆盖或重试。

通过上述方式确认的对象由外部对象存储的保留策略管理。变更沙箱、挂载或凭证前，先由存储所有者确认对象的保留、版本、备份、恢复、访问审计和后续清理方式；变更后，再从对象存储重新读取需要保留的对象。需要轮换 AccessKey 或 Secret Access Key 时，新建替代凭证、验证挂载、迁移所有引用，再删除旧凭证；编辑现有凭证只能修改名称、区域和访问地址，不能替换存储类型或 AccessKey。

注意

读写挂载可能产生覆盖、并发写入和外部费用。AgentWorks 不把挂载声明为数据库事务、分布式锁或强一致文件系统。生产写入前，应使用目标应用和对象存储完成恢复、重复执行与并发测试。

需要用固定合成数据验证只读规则、只读输入和读写报告，并从对象存储核对报告哈希时，参见构建订单与退款交付验收助手。

将沙箱接入智能体

创建沙箱资源后，还要把它添加到智能体模板，并确认环境中已有任务所需的命令、文件、运行时和依赖。

将沙箱添加到智能体模板

1. 创建或编辑智能体模板，打开 插件配置。
2. 单击 添加插件。
3. 默认选择 沙箱 - 模板，再选择目标模板。只有已经完成共享实例检查时，才选择 沙箱 - 实例。
4. 按需设置模板开放参数，然后保存智能体模板。
5. 在智能体模板详情页的 插件 页签中确认沙箱类型、名称和资源 ID。
6. 创建或更新智能体实例。

创建或更新智能体实例后，请运行实际命令验证沙箱环境。

使用沙箱提供微应用界面

微应用是预先开发并随兼容沙箱环境交付的自定义交互界面，不是由 AgentWorks 配置页面生成的网页。将一个沙箱标记为微应用后，AgentWorks 会在该智能体实例的 Playground 中加载这个界面，并把界面请求交给同一沙箱中的配套服务。该沙箱仍可向智能体提供工具。

微应用适合仅靠聊天不便完成的任务，例如查看任务看板、编辑日程、填写表单或操作结构化业务数据。微应用只改变 Playground 中的交互界面；飞书、QQ、Invoke API 和 WebSocket 仍使用各自的接入方式。

使用租户已有的微应用时，智能体构建者无需编写代码，只需选择对应的沙箱环境。需要新的微应用时，由平台提供方或企业研发团队先开发并交付兼容的沙箱镜像，再由平台管理员将其配置为租户可用的沙箱环境。

重要

先使用已准备好的微应用环境

选择 微应用 只指定由哪个沙箱提供界面，不会创建、构建或部署微应用。只有所选沙箱环境明确支持目标微应用时，才启用该选项。

注意

多个智能体可能共用同一个微应用沙箱

选择 沙箱 - 模板 时，每个智能体实例会获得自己的沙箱。选择 沙箱 - 实例 时，所有智能体会使用同一个微应用服务和沙箱内状态；新建会话或更换最终用户不会把这些内容分开。无法确认是否应共享时，请选择 沙箱 - 模板。

1. 在智能体模板的 插件配置 中添加兼容的沙箱模板或实例。
2. 在目标沙箱下选择 微应用。每个智能体模板只能指定一个微应用沙箱；选择另一个沙箱会取消原有选择。
3. 保存智能体模板，再创建或更新测试智能体实例。
4. 打开 Playground，确认自定义界面能够加载，并完成一次可撤销的测试操作。
5. 如果微应用还需要智能体调用沙箱工具，使用低风险输入触发工具，并在 Trace 和 沙箱运行记录 中核对结果。

准备命令、文件和运行依赖

使用 Skill 脚本前，先确认文件如何进入沙箱：

• 智能体模板同时使用技能组和 沙箱 - 模板 时，平台会把所选 Skill 文件只读挂载到新沙箱的 /skills 目录。执行前，请列出该目录并找到目标 Skill；存在同名 Skill 时，目录名可能带有附加标识。
• 选择 沙箱 - 实例 时，平台不会复制该智能体的 Skill 文件。请先确认所需文件已经存在，并评估修改这些文件会影响哪些智能体。

文件已经出现在沙箱中，不表示平台会自动运行脚本。智能体仍需调用沙箱工具执行文件，所需运行时和依赖也必须已经安装在环境中。

然后：

1. 选择已经包含所需命令、运行时和依赖的环境。
2. 配置正确的工作目录和环境变量。把输出写到可写工作目录，不要尝试修改 /skills。
3. 把沙箱模板或实例添加到智能体模板，并创建或更新智能体实例。
4. Skill 或技能组的版本选择发生变化后，先更新或重新创建非生产智能体实例，并核对实际文件，再更新生产实例。
5. 先运行一个只读、可预测的测试命令，再运行真实任务。

需要使用最终用户的业务凭证时，优先通过用户工具包或在沙箱外完成授权的 MCP 服务执行。确需向沙箱提供凭证时，应使用最小权限和最短有效期，并且不要让不应使用该凭证的智能体共享这个沙箱。

需要长期保留的文件和结果应写入已批准的外部存储。每次写入后，从对象存储控制台按完整路径重新读取，或者使用全新替代沙箱读取同一对象。沙箱工作目录只用于运行任务；目标环境另有数据保留说明时，按该说明管理副本和保留时间。

Skill 自动挂载只提供文件，不会执行脚本、安装依赖或注册工具。不要把 Skill ZIP 当作沙箱镜像或依赖安装包。测试时，请分别确认 Skill 已激活、文件已进入沙箱，以及沙箱工具已经执行文件。

选择沙箱隔离范围

先决定哪些智能体可以使用同一个工作区：

• 每个智能体实例需要自己的沙箱时，在智能体模板中选择沙箱模板。
• 多个智能体实例需要共享沙箱时，显式选择同一个现有沙箱实例。

Agent API 不会为新会话、线程、调用任务或单次运行自动创建沙箱。

目标	是否支持	做法
每个智能体实例使用不同沙箱	支持	在智能体模板中选择沙箱模板
多个智能体实例共享沙箱	支持	显式选择同一个现有沙箱实例，并共同管理文件、Skill、配置和清理
每个渠道用户使用不同沙箱	间接支持	使用渠道模板绑定，让每位用户通过 /init 创建智能体实例，并让智能体模板选择沙箱模板
每个 API 用户或业务租户使用不同沙箱	不自动支持	为相应隔离范围分别准备智能体实例，并让每个实例通过沙箱模板获得沙箱
每段会话或线程使用新沙箱	不支持	新建 session_id 或渠道会话不会创建、切换或清空沙箱
每个调用任务或单次运行使用新沙箱	不支持	新的 Invoke 请求、调用任务、中断响应或任务重置不会创建、切换或清空沙箱

注意

会话和调用任务不是沙箱边界

新建会话、更换渠道用户或 API 调用方，不会自动创建新的沙箱。多个最终用户使用同一个智能体实例时，仍使用该实例关联的沙箱。即使不同智能体实例来自不同用户，只要它们选择同一个现有沙箱实例，沙箱仍然共享。

session_id 只标识 API 对话。Agent API Token 不能创建、绑定或删除沙箱，Invoke 请求也不能指定沙箱。新建会话、开始新任务或调用 ResetMissionState 都不会重建或清空沙箱。

为会话或调用任务使用外部隔离环境

每段会话或每次运行都需要全新执行环境时，请使用由业务系统管理的外部执行服务。通过 Invoke API 或 WebSocket 接入的业务系统，可以通过用户工具包接收工具中断，并在外部服务中完成操作：

• 每段会话使用新环境：业务系统创建外部环境，记录它与 AgentWorks session_id 的对应关系，并在会话结束或过期后销毁环境。
• 每次运行使用新环境：业务系统为本次运行创建外部环境，在运行结束、失败或超时后销毁环境。

这个外部环境不是 AgentWorks 沙箱，只用于执行用户工具。模型运行、平台工具包和已经关联的沙箱工具仍在原来的位置执行。

如果使用远程 MCP Server 管理外部环境，业务系统必须向它提供并校验可信的用户或会话标识。不要根据模型生成的环境 ID 选择执行环境。

如果工具必须在 AgentWorks 沙箱内运行，请提前分别创建智能体实例和沙箱。不能通过 Agent API 为每段会话或每次运行动态创建沙箱。

需要使用最终用户的业务凭证时，优先使用用户工具包或在沙箱外完成用户授权的 MCP 服务。不要把用户专用的原始凭证放入由其他用户或智能体实例共享的沙箱。

不同的沙箱资源 ID 只表示配置了不同沙箱，不表示外部账号、凭证、知识、记忆或业务权限已经自动隔离。资源 ID 也不能说明沙箱会持续运行多久或文件会保留多久。

运行测试并检查限制

上线前，请确认智能体调用了预期工具、沙箱实际执行了预期命令，并检查工具权限、网络和资源限制是否生效。

限制沙箱网络和资源

平台管理员可以在规格中配置带宽、私网地址出站控制、DNS 允许或拒绝列表、超时和空闲回收。生产规格应按最小权限开放网络，并为长任务设置合理超时。

这些控制属于规格。普通用户不能在每个沙箱模板中任意扩大管理员分配的资源或网络权限。

检查 Trace 和沙箱运行记录

检查两个位置：

• 在 Trace 中确认智能体调用了预期工具。如果使用 Skill，还要确认 Skill 已激活并读取了正确版本。
• 在 沙箱运行记录 中确认实际执行的命令和结果。

排查问题时，还要检查：

• 智能体实例是否运行。
• 沙箱实例和规格是否可用。
• 环境变量是否按实例参数生成。
• 网络策略是否允许目标地址。
• 智能体模板的 工具权限 是否按预期自动拒绝、自动批准或发出人工审批中断。

测试沙箱执行

把沙箱模板或实例添加到测试智能体模板，并创建两个非生产智能体实例。按以下顺序验证：

1. 核对两个智能体实例关联的沙箱资源 ID。

   • 选择沙箱模板时，两个沙箱资源 ID 应不同。
   • 选择现有沙箱实例时，两个资源 ID 应相同，并应把共享关系记录为有意配置。如果两个智能体需要不同 Skill 集合，应停止测试，不要发布，并改用沙箱模板。

2. 确认沙箱实例使用预期规格和环境，环境变量按模板参数生成。

3. 需要使用 Skill 文件时，按关联方式验证文件：

   • 同时关联技能组和沙箱模板时，列出 /skills，核对目标 Skill 和所选版本中的文件。
   • 选择现有沙箱实例时，核对所需文件已经在该实例中另行准备。

4. 在两个智能体实例中分别运行一个只读、可预测的测试命令。确认 Playground 可以使用沙箱命令或文件工具；沙箱实例已经生成或文件已经挂载，不等于运行时会自动执行脚本。

5. 确认工作目录和镜像内所需命令存在，网络只允许测试所需目标。

6. 在沙箱运行记录和 Trace 中核对实际工具名称、结果、审批行为和目标智能体实例。

7. 服务将由多个用户使用时，再以具有代表性的非生产调用方身份执行测试。

8. 如果沙箱已标记为微应用，继续验证微应用界面，确认界面行为和共享方式符合预期。

9. 删除测试文件和不再需要的测试资源。

资源 ID 只能说明智能体配置关联了哪个沙箱。需要确认不同用户能否看到彼此的数据或使用彼此的权限时，请使用虚构数据，分别以应该能访问和不应该能访问的测试身份进行验证。不要使用生产凭证。

需要为沙箱工具配置权限规则时，在沙箱实例详情中加载工具列表并复制实际工具名称，再编辑智能体模板的 工具权限。沙箱没有单独的审批开关。工具列表只显示工具名称和描述。参见配置工具审批流程。

如果规则需要检查参数值，请先保留人工审批。通过一次低风险测试在 Trace 中核对实际参数，或查阅工具的公开说明。无法确认参数结构时，不要猜测参数名或创建宽泛允许规则。参见找到工具名称和参数名。

如果智能体模板还关联了技能组，请分别核对各项结果：在 Trace 中确认 Skill 激活和资源读取；在沙箱运行记录中确认沙箱工具执行；从对象存储端重新读取写入挂载路径的文件。需要确认 Skill 文件已经进入 /skills 或现有沙箱时，再从对应沙箱路径读取并核对文件。

再发起一次应被模板规则拒绝的工具调用，确认工具没有执行。另行访问一个应被网络策略拒绝的地址，确认网络限制同样生效。

处理超时、网络和启动失败

• 启动慢：确认管理员规格是冷启动还是预热启动，并检查资源是否可用。
• 命令超时：比较任务时长、规格运行超时和智能体实例调用超时，不要只扩大其中一个值。
• 域名无法解析：检查规格的 DNS 允许和拒绝列表，拒绝列表优先。
• 私网地址不可达：检查 RFC1918 出站限制和例外 CIDR。
• 镜像或命令不存在：检查环境镜像、工作目录和镜像版本。
• 没有可选规格或环境：让管理员确认资源已分配给当前租户且类型匹配。
• 微应用界面未加载或操作失败：确认智能体实例已更新、目标沙箱已标记为微应用，并且所选环境明确支持目标微应用。继续参见排查微应用界面。

不要通过永久放开所有网络或取消所有超时来解决单次失败。

安全修改或删除沙箱

修改共享沙箱实例会影响所有使用它的智能体模板和智能体实例。生产清单应记录来源沙箱模板、实际沙箱资源 ID、规格、环境、使用它的智能体和清理负责人。

需要分阶段变更时，创建替代实例或模板，在测试智能体实例中验证后再切换生产引用。修改沙箱模板、规格或环境，不表示已经创建或正在运行的沙箱已经迁移；请核对受影响的资源 ID，并重复执行测试。

删除沙箱模板后，请在实例列表中检查并分别处理相关沙箱实例。删除沙箱实例前，先移除智能体模板和智能体实例引用，保留必要运行记录，并确认实例工作目录中没有仍需留存的数据。

仍被模板或实例引用的规格和环境不能删除。请先迁移所有引用，再执行删除。