概念

现代智能体能够在文件系统中操作真实文件时，通常可以发挥最佳效果。沙盒智能体可以使用专用工具和 shell 命令搜索并处理大型文档集、编辑文件、生成产物和运行命令。沙盒为模型提供持久工作区，智能体可在其中代您完成工作。Agents SDK 中的沙盒智能体可帮助您运行与沙盒环境配套的智能体，让您能够轻松地将所需文件放入文件系统，并大规模编排沙盒以启动、停止和恢复任务。

您可以围绕智能体所需的数据定义工作区。全新的工作区可通过 GitHub 仓库、本地文件和目录、合成任务文件、S3 或 Azure Blob Storage 等远程文件系统，以及您提供的其他沙盒输入进行填充。

SandboxAgent 扩展了 Agent，因此它仍然是一个 Agent。它保留了常规智能体接口，例如 instructions、tools、handoffs、mcpServers、modelSettings、输出类型、护栏和钩子，并且仍通过常规的 run() 和 Runner API 运行。变化在于执行边界：

SandboxAgent 定义智能体本身：常规智能体配置，以及 defaultManifest、baseInstructions、runAs 等沙盒特定默认值，还有文件系统工具、shell 访问、技能、记忆或压缩等能力。
Manifest 声明全新沙盒工作区所需的初始内容和布局，包括文件、仓库、挂载和环境。
沙盒会话是命令运行和文件发生变化的实时执行环境。
sandbox 运行选项决定本次运行如何获取沙盒会话，例如直接注入会话、通过序列化的沙盒会话状态重新连接，或使用沙盒客户端创建全新的沙盒会话。
已保存的沙盒状态和快照让后续运行可以重新连接到之前的工作，或使用已保存的内容初始化全新的沙盒会话。

Manifest 定义新沙盒工作区的初始内容。它并不描述每个实时沙盒中的当前文件，因为复用的会话、序列化的会话状态和快照都可以在运行时提供或更改工作区。

在本页中，“沙盒会话”是指由沙盒客户端管理的实时执行环境。具体边界取决于客户端：Unix 本地会话在主机上的本地工作区中运行，而 Docker 和托管客户端提供更强的环境隔离。这不同于会话中介绍的 SDK 对话式 Session 接口。

外层运行时仍负责审批、追踪、交接和恢复记录。沙盒会话负责命令、文件更改和环境隔离。这种职责划分是该模型的核心组成部分。

各组件的协作方式

一次沙盒运行会将智能体定义与每次运行的沙盒配置结合起来。运行器会准备智能体，将其绑定到实时沙盒会话，并可保存状态供后续运行使用。

SandboxAgent智能体及沙盒默认值

Runner准备指令并绑定能力工具

沙盒会话命令运行和文件发生变化的工作区

已保存状态稍后恢复或初始化全新工作区

沙盒特定默认值保留在 SandboxAgent 上。每次运行的沙盒会话选择则保留在 sandbox 运行选项中。

可以将生命周期分为三个阶段：

使用 SandboxAgent、Manifest 和能力定义智能体及工作区的初始内容。
向 run() 或 Runner 提供 sandbox 运行选项，通过注入、恢复或创建沙盒会话来执行运行。
稍后从运行器管理的 RunState、显式沙盒 sessionState 或已保存的工作区快照继续运行。

如果只是偶尔需要 shell 访问，请从工具中的托管 shell 开始。当工作区隔离、沙盒客户端选择或沙盒会话恢复行为属于设计的一部分时，请使用沙盒智能体。

适用场景

沙盒智能体非常适合以工作区为中心的工作流，例如：

编码和调试：针对 GitHub 仓库中的问题报告编排自动修复，并运行有针对性的测试。
文档处理和编辑：从用户的财务文档中提取信息，并创建填写完成的税务表单草稿。
基于文件的审查或分析：在回答前检查入职资料包、生成的报告或产物包。
隔离的多智能体模式：为每个审查智能体或编码子智能体提供各自的工作区。
多步骤工作区任务：在一次运行中修复错误，稍后添加回归测试，或从快照或沙盒会话状态恢复。

如果不需要访问文件或持续存在的文件系统，请继续使用 Agent。如果 shell 访问只是偶尔使用的一项能力，请添加托管 shell；如果工作区边界本身就是功能的一部分，请使用沙盒智能体。

沙盒客户端选择

在 macOS 或 Linux 上进行本地开发时，请从 UnixLocalSandboxClient 开始。在 Windows 上，请改用 DockerSandboxClient 或托管提供商。在任何受支持的平台上，如果需要容器隔离或镜像一致性，请迁移到 DockerSandboxClient；如果需要由提供商管理执行，请迁移到托管提供商。

大多数情况下，SandboxAgent 定义保持不变，只需在 sandbox 运行选项中更改沙盒客户端及其选项。有关本地、Docker、托管和远程挂载选项，请参阅沙盒客户端。

核心组件

层级	主要 SDK 组件	回答的问题
智能体定义	`SandboxAgent`、`Manifest`、能力	将运行哪个智能体，它应以怎样的全新会话工作区约定开始？
沙盒执行	`sandbox` 运行选项、沙盒客户端和实时沙盒会话	本次运行如何获取实时沙盒会话，工作在哪里执行？
已保存的沙盒状态	`RunState` 沙盒载荷、`sessionState` 和快照	此工作流如何重新连接到之前的沙盒工作，或使用已保存的内容初始化全新的沙盒会话？

主要 SDK 组件与这些层级的对应关系如下：

组件	负责的内容	要问的问题
`SandboxAgent`	智能体定义	此智能体应该做什么，哪些默认值应随其一起使用？
`Manifest`	全新会话的工作区文件和文件夹	运行开始时，文件系统中应存在哪些文件和文件夹？
`Capability`	沙盒原生行为	应将哪些工具、指令片段或运行时行为附加到此智能体？
`sandbox` 运行选项	每次运行的沙盒客户端和沙盒会话来源	本次运行应注入、恢复还是创建沙盒会话？
`RunState`	由运行器管理的已保存沙盒状态	我是否正在恢复之前由运行器管理的工作流，并自动延续其沙盒状态？
`sandbox.sessionState`	显式序列化的沙盒会话状态	我是否要从已在 `RunState` 外部序列化的沙盒状态恢复？
`sandbox.snapshot`	用于全新沙盒会话的已保存工作区内容	新沙盒会话是否应从已保存的文件和产物开始？

实用的设计顺序如下：

使用 Manifest 或清单初始化对象定义全新会话的工作区约定。
使用 SandboxAgent 定义智能体。
添加内置或自定义能力。
决定每次运行应如何在 run(agent, input, { sandbox: ... }) 或 new Runner({ sandbox: ... }) 中获取沙盒会话。

沙盒运行的准备方式

在运行时，运行器会将该定义转换为具体的沙盒支持型运行：

从 sandbox 运行选项中解析沙盒会话。
确定本次运行的有效工作区输入。
让各项能力处理生成的清单。
按固定顺序构建最终指令：SDK 的默认沙盒提示；如果您显式覆盖了它，则使用 baseInstructions；随后是 instructions、能力指令片段、任何远程挂载策略文本，最后是渲染后的文件系统树。
将能力工具绑定到实时沙盒会话，并通过常规的 run() 和 Runner API 运行准备好的智能体。

沙盒机制不会改变轮次的含义。一个轮次仍是一次模型步骤，而不是单个 shell 命令或沙盒操作。沙盒侧操作与轮次之间不存在固定的一对一映射。实用的判断规则是：只有在完成沙盒工作后，智能体运行时需要模型再次响应，才会消耗另一个轮次。

`SandboxAgent` 选项

以下是在常规 Agent 字段之外的沙盒特定选项：

选项	最佳用途
`defaultManifest`	运行器创建的全新沙盒会话所使用的默认工作区。
`instructions`	追加在 SDK 沙盒提示之后的额外角色、工作流和成功标准。
`baseInstructions`	用于替换 SDK 沙盒提示的高级逃生舱。
`capabilities`	应随此智能体一起使用的沙盒原生工具和行为。
`runAs`	用于面向模型的沙盒工具（例如 shell 命令、文件读取和补丁）的用户身份。

沙盒客户端选择、沙盒会话复用、清单覆盖和快照选择应放在 sandbox 运行选项中，而不是智能体上。

`defaultManifest`

defaultManifest 是运行器为此智能体创建全新沙盒会话时使用的默认工作区。可传入 Manifest 实例，或您会传给 new Manifest(...) 的同类初始化对象。它适用于智能体通常应在开始时拥有的文件、仓库、辅助材料、输出目录和挂载。

defaultManifest 仅提供默认工作区。运行可以通过 sandbox.manifest 覆盖 defaultManifest，而复用或恢复的沙盒会话会保留其现有工作区状态。

import { file, gitRepo, Manifest } from '@openai/agents/sandbox';

const manifest = new Manifest({
  root: '/workspace',
  entries: {
    'task.md': file({
      content: 'Fix the failing test and summarize the change.',
    }),
    repo: gitRepo({
      repo: 'openai/openai-agents-js',
      ref: 'main',
    }),
  },
  environment: {
    NODE_ENV: 'test',
  },
});

`instructions` 和 `baseInstructions`

使用 instructions 设置应在不同提示下保持不变的简短规则。在 SandboxAgent 中，这些指令会追加到 SDK 的沙盒基础提示之后，因此您可以保留内置沙盒指导，同时添加自己的角色、工作流和成功标准。

仅当您想替换 SDK 的沙盒基础提示时，才使用 baseInstructions。大多数智能体不应设置它。

放置位置	用途	示例
`instructions`	智能体稳定的角色、工作流规则和成功标准。	“检查入职文档，然后进行交接。”、“将最终文件写入 `output/`。“
`baseInstructions`	完整替换 SDK 的沙盒基础提示。	自定义底层沙盒封装提示。
用户提示	本次运行的一次性请求。	“总结此工作区。“
清单中的工作区文件	较长的任务规范、仓库本地指令或范围明确的参考材料。	`repo/task.md`、文档包、示例资料包。

请避免将用户的一次性任务复制到 instructions 中、嵌入本应放在清单中的长篇参考材料、重复内置能力已经注入的工具文档，或混入模型在运行时不需要的本地安装说明。

`capabilities`

能力可将沙盒原生行为附加到 SandboxAgent。它们可以在运行开始前调整工作区、追加沙盒特定指令、公开绑定到实时沙盒会话的工具，以及调整该智能体的模型行为或输入处理方式。

内置能力包括：

能力	添加时机	说明
`shell()`	智能体需要 shell 访问。	添加 `exec_command`；当沙盒客户端支持 PTY 交互时，还会添加 `write_stdin`。
`filesystem()`	智能体需要编辑文件或检查本地图像。	添加 `apply_patch` 和 `view_image`；默认情况下，相对路径从工作区根目录开始，配置了 `sandbox.cwd` 时则从该目录开始。
`skills()`	您希望在沙盒中发现并具体化技能。	对于沙盒本地的 `SKILL.md` 技能，优先使用此能力，而不是手动挂载 `.agents` 或 `.agents/skills`。
`memory()`	后续运行应读取或生成记忆产物。	需要 `shell()`；实时更新还需要 `filesystem()`。
`compaction()`	长时间运行的流程需要在压缩项出现后精简上下文。	调整模型采样和输入处理。

默认情况下，SandboxAgent.capabilities 使用 Capabilities.default()，其中包括 filesystem()、shell() 和 compaction()。如果传入 capabilities: [...]，该列表将替换默认列表，因此请包含您仍想使用的所有默认能力。

view_image 接受最大 10 MB 的 PNG、JPEG、GIF、WebP、BMP、TIFF 和 SVG 图像。SDK 通过文件签名检测光栅格式，而不是信任光栅图像的文件扩展名，因此仅有光栅图像扩展名并不能使不受支持的字节内容变得有效。SDK 可通过 SVG 内容或 .svg、.svgz 文件名识别 SVG。

compaction() 默认使用 DynamicCompactionPolicy。对于可识别的模型，当渲染后的上下文达到该模型上下文窗口的 90% 时，该策略会请求 Responses API 执行压缩。如果缺少模型或模型未知，该策略使用 240,000 个 token 的回退阈值。可以向 new DynamicCompactionPolicy(thresholdRatio, fallbackThreshold) 传入不同的比例和回退阈值；如果所有受支持模型都应使用同一个固定 token 阈值，则使用 new StaticCompactionPolicy(threshold)。动态比例必须是从 0 到 1 的有限数值。

当服务器端压缩生成压缩项时，该能力会保留该项及后续输入，同时丢弃更早的重放项。压缩项是不透明的模型状态，而不是人类可读的摘要，因此请原样传递，不要编辑。这些控制仅适用于支持 Responses 压缩的模型传输方式。

概念

清单

Manifest 描述全新沙盒会话的工作区。它可以设置工作区 root、声明文件和目录、复制本地文件、克隆 Git 仓库、附加远程存储挂载、设置环境变量、定义用户或组，以及授权访问工作区之外的特定绝对路径。

默认情况下，清单环境值会被持久化。对于不应随沙盒状态一起保存的 API 密钥、访问令牌或其他短期凭据，请使用 { value: "...", ephemeral: true } 等临时条目。

对于在清单具体化或恢复时必须重新查找的密钥，请继承 EnvValueReference 并通过 registerEnvValueReference() 注册。引用仅持久化非敏感的查找元数据，并通过 resolve() 解析当前运行时值。每个子类都必须声明自己稳定、非空的静态 type，且 serialize() 不得包含保留的 value 字段。在重建清单之前，应在每个进程中注册解析器，并让解析器验证查找键并将其加入允许列表。恢复包含持久化 RunState 环境引用的状态时，需要提供带有相应引用条目的当前可信清单；否则，SDK 会在恢复会话前拒绝该操作。

清单条目路径相对于工作区。它们不能是绝对路径，也不能使用 .. 逃逸工作区，从而确保工作区约定可在本地、Docker 和托管客户端之间移植。

使用清单条目提供智能体开始工作前所需的材料：

清单条目	用途
`file()`、`dir()`	小型合成输入、辅助文件或输出目录。
`localFile()`、`localDir()`	应具体化到沙盒中的主机文件或目录。
`gitRepo()`	应提取到工作区中的仓库。
`s3Mount()`、`gcsMount()`、`r2Mount()`、`azureBlobMount()`、`s3FilesMount()` 等挂载	应出现在沙盒内的外部存储。

对于本地具体化，localFile() 和 localDir() 的源路径必须位于本地源基础目录中。默认基础目录是 Node 进程的当前工作目录，本地沙盒客户端在具体化条目时可以提供客户端特定的基础目录。如果源必须来自另一个绝对主机目录，请添加范围尽可能小的必要 Manifest.extraPathGrants 条目。

本地延迟技能发现也会使用 extraPathGrants。指向源基础目录之外的 localDirLazySkillSource() 会被忽略，除非清单授予了对该目录的访问权限。对于共享技能、数据集和参考仓库等输入包，请优先使用 readOnly: true。

每项路径授权都有一个沙盒路径，并可在需要时提供单独的主机路径：

path 是沙盒内可见的绝对 POSIX 路径。
hostPath 是可选的绝对原生主机路径，用于主机路径和沙盒路径不同时。在 Windows 上，它必须包含驱动器限定符；不支持 UNC 路径和设备路径。

UnixLocalSandboxClient 要求主机路径和沙盒路径相同，因此请省略其中的 hostPath。如果创建容器时使用的清单中包含授权，DockerSandboxClient 支持单独的 hostPath。它无法在已运行的容器上添加或更改该映射。Docker 命令可以将创建时授权的沙盒路径用作其 workdir；工作区和已配置授权之外的路径仍会被拒绝。

import { Manifest, localDir, skills } from '@openai/agents/sandbox';
import { localDirLazySkillSource } from '@openai/agents/sandbox/local';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const appRoot = dirname(fileURLToPath(import.meta.url));
const repoDir = join(appRoot, 'repo');
const sharedSkillsDir = '/opt/company/agent-skills';

const manifest = new Manifest({
  extraPathGrants: [
    {
      path: sharedSkillsDir,
      readOnly: true,
      description: 'Shared skill bundle.',
    },
  ],
  entries: {
    repo: localDir({ src: repoDir }),
  },
});

const skillCapability = skills({
  lazyFrom: localDirLazySkillSource({
    src: sharedSkillsDir,
  }),
});

挂载条目描述要公开的存储，挂载策略则描述沙盒后端如何附加该存储。有关挂载选项和提供商支持，请参阅沙盒客户端。

权限

Permissions 控制清单条目的文件系统权限。它针对的是沙盒具体化的文件，而不是模型权限、审批策略或 API 凭据。

用户是可以在沙盒中执行工作的身份。如果您希望某个身份存在于沙盒中，请将该用户添加到清单；如果 shell 命令、文件读取和补丁等面向模型的沙盒工具应以该用户身份运行，请设置 SandboxAgent.runAs。

如果还需要文件级共享规则，请将用户与清单组和条目 group 元数据结合使用。runAs 用户控制由谁执行沙盒原生操作；Permissions 则控制沙盒具体化工作区后，该用户可以读取、写入或执行哪些文件。

SnapshotSpec

SnapshotSpec 指定全新沙盒会话应从哪里恢复已保存的工作区内容，以及将内容持久化回哪里。它是沙盒工作区的快照策略，而 sessionState 是用于恢复特定沙盒后端的序列化连接状态。

对于本地持久快照，请使用本地快照；当您的应用提供远程快照客户端时，请使用远程快照。挂载路径和临时路径不会作为持久工作区内容复制到快照中。在水合期间，SDK 会先拒绝与任何受保护的挂载路径或临时路径重叠的归档成员，然后才会将归档写入工作区。如果工作区根目录本身是临时目录，则只能水合空归档。

沙盒生命周期

生命周期分为两种模式：SDK 所有和开发者所有。

SDK 所有运行器拥有实时沙盒。

传入 sandbox.client。
运行器创建或恢复沙盒会话。
智能体运行，并可持久化由快照支持的工作区状态。
运行器关闭其所有的资源。

开发者所有您的应用拥有实时沙盒。

创建 session。
将 sandbox.session 传入运行。
智能体使用现有工作区。
自行检查并复用会话，然后关闭会话。

当沙盒只需在一次运行期间存在时，请使用 SDK 所有的生命周期。传入 client、可选的 manifest、可选的 snapshot 和客户端 options；运行器会创建或恢复沙盒、运行智能体、持久化由快照支持的工作区状态，并让客户端清理由运行器所有的资源。

import { run } from '@openai/agents';
import { SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the sandbox workspace before answering.',
});

const result = await run(agent, 'Inspect the workspace.', {
  sandbox: {
    client: new UnixLocalSandboxClient(),
  },
});

console.log(result.finalOutput);

如果您希望提前创建沙盒、在多次运行中复用一个实时沙盒、在运行后检查文件、通过自己创建的沙盒进行流式传输，或精确决定清理时机，请使用开发者所有的生命周期。传入 session 会指示运行器使用该实时沙盒，但运行器不会替您关闭它。

import { run } from '@openai/agents';
import { Manifest, SandboxAgent } from '@openai/agents/sandbox';
import { UnixLocalSandboxClient } from '@openai/agents/sandbox/local';

const manifest = new Manifest();
const agent = new SandboxAgent({
  name: 'Workspace reviewer',
  model: 'gpt-5.6-sol',
  instructions: 'Inspect the sandbox workspace before answering.',
});

const client = new UnixLocalSandboxClient();
const session = await client.create({ manifest });

try {
  await run(agent, 'First task.', { sandbox: { session } });
  await run(agent, 'Follow-up task.', { sandbox: { session } });
} finally {
  await session.close?.();
}

沙盒操作观测

沙盒操作事件为运行器管理的沙盒工作提供进程级可观测性。使用 addSandboxEventSink() 注册 SandboxEventSink，以接收 sandbox_operation 事件。每项操作都会先发出 start 阶段，随后发出 end 或 error；终止事件包含持续时间，错误事件则包含规范化的错误详情，例如提供商公开的错误代码或是否可重试。

当一次运行配置了 sandbox.cwd 时，sandbox.exec 事件数据会报告以有效 cwd 为基准的 workdir，而 sandbox.view_image 事件数据会报告以有效 cwd 为基准的 path。这些值与发送到沙盒会话的路径一致。

使用 createSandboxJsonlEventSink() 将每个事件写入一行 JSONL，使用 createSandboxHttpEventSink() 通过 HTTP POST 发送每个事件，或使用 createChainedSandboxEventSink() 将事件分发到多个接收器。addSandboxEventSink() 会返回移除函数；当应用不再需要该接收器时调用此函数，或使用 clearSandboxEventSinks() 移除所有已注册的接收器。

事件接收器仅用于观测。SDK 会等待已注册的接收器处理完成，但接收器失败不会替换沙盒操作的运行结果或错误。如果应用需要更强的交付保证，请在接收器内部处理交付重试、缓冲和接收器特定故障。

`sandbox` 运行选项

sandbox 运行选项包含每次运行的配置，用于决定沙盒会话的来源，以及应如何初始化全新会话。

沙盒来源

以下选项决定运行器应复用、恢复还是创建沙盒会话：

选项	使用场景	说明
`client`	您希望运行器替您创建、恢复和清理沙盒会话。	除非提供实时沙盒 `session`，否则为必需项。
`session`	您已经自行创建了实时沙盒会话。	调用方拥有生命周期；运行器复用该实时沙盒会话。
`sessionState`	您拥有序列化的沙盒会话状态，但没有实时沙盒会话对象。	需要 `client`；运行器根据该显式状态恢复，并拥有恢复后的会话。

工作目录

在 sandbox 运行配置中设置 cwd，可将相对于工作区的目录设为本次运行的工作目录。内置的 exec_command、view_image 和 apply_patch 工具从此目录解析相对路径；其他沙盒工具仍采用各自的路径约定。此设置会更改路径解析方式，但不会将本次运行与会话工作区的其余部分隔离。

该值必须是非空、相对于工作区的 POSIX 路径。绝对路径、反斜杠和父级（..）路径段都会被拒绝。在每次模型轮次之前，运行器会检查该目录是否存在，以及沙盒智能体的 runAs 身份是否可以访问该目录。与 cwd 一起使用的自定义或注入会话必须实现 directoryExists()。

全新会话输入

以下选项仅在运行器创建全新沙盒会话时有效：

选项	使用场景	说明
`manifest`	您希望对全新会话的工作区进行一次性覆盖。	接受 `Manifest` 或清单初始化对象。省略时回退到 `agent.defaultManifest`。
`snapshot`	全新沙盒会话应通过快照初始化。	适用于类似恢复的流程或远程快照客户端。
`options`	沙盒客户端需要创建时选项。	常用于 Docker 镜像、提供商超时和类似的客户端特定设置。

concurrencyLimits 控制可并行执行的沙盒具体化工作量。当大型清单或本地目录复制需要更严格的资源控制时，请使用 manifestEntries 和 localDirFiles。

具体化控制

具体化控制特意按每次运行设置。请将它们放在 sandbox 运行选项附近，以便同一个 SandboxAgent 可以对大型本地目录复制采用保守限制，对小型清单采用较宽松的限制。

当清单包含许多相互独立的条目（例如文件、目录、仓库和挂载）时，请使用 concurrencyLimits.manifestEntries。当 localDir() 条目包含大量文件，并且需要限制本地复制压力时，请使用 concurrencyLimits.localDirFiles。

归档安全限制

使用 archiveLimits 限制工作区水合和恢复期间的归档输入字节数、解压后字节数和成员数量。传入空对象会启用默认值：1 GiB 归档输入、4 GiB 解压内容和 100,000 个成员。将单个字段设置为 null 可仅禁用该项限制。省略 archiveLimits 或将整个选项设置为 null，会完全禁用归档限制。

完整示例：编码任务

以下编码风格的示例是一个很好的默认起点：

import { run } from '@openai/agents';
import {
  Capabilities,
  Manifest,
  SandboxAgent,
  localDir,
  skills,
} from '@openai/agents/sandbox';
import {
  UnixLocalSandboxClient,
  localDirLazySkillSource,
} from '@openai/agents/sandbox/local';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const exampleDir = dirname(fileURLToPath(import.meta.url));
const hostRepoDir = join(exampleDir, 'repo');
const hostSkillsDir = join(exampleDir, 'skills');

const manifest = new Manifest({
  entries: {
    repo: localDir({ src: hostRepoDir }),
  },
});

const agent = new SandboxAgent({
  name: 'Sandbox engineer',
  model: 'gpt-5.6-sol',
  instructions:
    'Read `repo/task.md` before editing files. Load the `$invoice-total-fixer` skill before changing code. Stay grounded in the repository, preserve existing behavior, and mention the exact verification command you ran. If you edit files with apply_patch, paths are relative to the sandbox workspace root.',
  defaultManifest: manifest,
  capabilities: [
    ...Capabilities.default(),
    skills({
      lazyFrom: localDirLazySkillSource({
        src: hostSkillsDir,
      }),
    }),
  ],
});

const result = await run(
  agent,
  'Open `repo/task.md`, fix the issue, run the targeted test, and summarize the change.',
  {
    sandbox: {
      client: new UnixLocalSandboxClient(),
    },
  },
);

console.log(result.finalOutput);

常见模式

请从上面的完整示例开始。在许多情况下，同一个 SandboxAgent 可以保持不变，只需更改沙盒客户端、沙盒会话来源或工作区来源。

沙盒客户端切换

保持智能体定义不变，仅更改运行配置。如果需要容器隔离或镜像一致性，请使用 Docker；如果需要由提供商管理执行，请使用托管提供商。有关代码示例和提供商选项，请参阅沙盒客户端。

工作区覆盖

保持智能体定义不变，仅使用 sandbox: { client, manifest } 替换全新会话的清单。当同一个智能体角色需要针对不同的仓库、资料包或任务包运行，而您不希望重新构建智能体时，请使用此模式。

沙盒会话注入

当需要显式控制生命周期、在运行后检查内容或复制输出时，请注入实时沙盒会话。对该次运行使用 sandbox: { session }，并在应用代码中关闭会话。

会话状态恢复

如果您已在 RunState 外部序列化沙盒状态，可通过 sandbox: { client, sessionState } 让运行器根据该状态重新连接。当沙盒状态保存在您自己的存储或作业系统中，并且您希望 Runner 直接从中恢复时，请使用此模式。

快照启动

使用 sandbox: { client, snapshot }，通过已保存的文件和产物初始化新沙盒。当全新运行应从已保存的工作区内容开始，而不仅仅使用 agent.defaultManifest 时，请使用此模式。

从 Git 加载技能

使用 skills({ from: gitRepo(...) }) 将本地技能源替换为由仓库支持的技能源。当技能包拥有自己的发布节奏或应在多个沙盒之间共享时，请使用此模式。

工具形式公开

工具智能体既可以拥有自己的沙盒边界，也可以复用父级运行中的实时沙盒。复用适用于快速的只读探索智能体：它可以检查父级正在使用的同一工作区，而无需为另一个沙盒支付创建、水合或生成快照的成本。

如果工具智能体需要真正的隔离，请通过 sandboxAgent.asTool(...) 为其提供独立的 runConfig。当工具智能体应自由修改内容、运行不受信任的命令，或使用不同的后端或镜像时，请使用单独的沙盒。

与本地工具和 MCP 的组合

在保留沙盒工作区的同时，仍可在同一个智能体上使用常规工具。沙盒能力可与 tools、mcpServers、交接、模型设置和输出配置共存。

智能体记忆

当未来的沙盒智能体运行需要从先前运行中学习时，请使用 memory() 能力。记忆与 SDK 的对话式 Session 记忆不同：它会将经验提炼为沙盒工作区中的文件，供后续运行读取。

有关设置、读取和生成行为、多轮对话及布局隔离，请参阅智能体记忆。

组合模式

理解单智能体模式后，下一个设计问题是在更大的系统中应将沙盒边界放在哪里。

沙盒智能体仍可与 SDK 的其他部分组合：

交接：将文档密集型工作从非沙盒的接收智能体交接给沙盒审查智能体。
Agents as tools：将多个沙盒智能体公开为工具，通常是在每次调用 asTool(...) 时传入沙盒运行配置，以便每个工具获得自己的沙盒边界。
MCP 和常规函数工具：沙盒能力可以与 mcpServers 和常规工具共存。
运行智能体：沙盒运行仍使用常规的 run() 和 Runner API。

使用交接时，仍然只有一次顶层运行和一个顶层轮次循环。活动智能体会发生变化，但该运行不会变为嵌套运行。

使用 asTool(...) 时，两者的关系有所不同。外层编排器使用一个外层轮次决定调用工具，而该工具调用会为沙盒智能体启动一次嵌套运行。嵌套运行拥有自己的轮次循环、maxTurns、审批流程，并且通常拥有自己的沙盒运行配置。从外层编排器的角度来看，所有这些工作仍位于一次工具调用之后，因此嵌套轮次不会增加外层运行的轮次计数器。

概念