如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

沙盒智能体

在基于容器的环境中运行智能体任务,使用文件、命令、软件包、端口和快照,并可从保存的状态继续工作。

沙盒为智能体提供隔离的类 Unix 执行环境,其中包含文件系统、Shell、已安装的软件包、挂载的数据和对外开放的端口。智能体可以在其中使用快照,并在受控条件下访问外部系统。

如果模型需要这样的工作空间,却只能获取提示词上下文,智能体工作流就容易出问题。处理大量文档、生成产物、运行命令、查看预览以及恢复之前的工作,都需要一个智能体可以检查和修改的环境。

TypeScript 和 Python 版 Agents SDK 均支持沙盒智能体。

本指南介绍 Agents SDK 中的沙盒,其执行框架由您的应用运行。如果需要由 OpenAI 托管执行框架,请参阅 Agents API:连接沙盒。

当智能体需要操作文件、运行命令、挂载资料室、生成产物、对外提供服务,或在之后从已有状态继续工作时,请使用沙盒。

执行框架与计算环境各有分工。执行框架是围绕模型构建的控制平面,负责智能体循环、模型调用、工具路由、任务移交、审批、追踪、恢复和运行状态管理。计算环境则是沙盒的执行平面,智能体在模型的指导下读写文件、运行命令、安装依赖项、使用挂载的存储、开放端口,以及创建状态快照。

将两者分开后,您的应用可以在可信基础设施中处理控制平面上的敏感操作,由沙盒负责在相应提供商的环境中执行任务。沙盒可以使用权限范围有限的凭据和挂载资源运行代码来处理文件。执行框架则可以在容器之外处理身份验证、计费和人工审核,并保存审计日志和恢复状态,无需依赖某个特定容器。

在沙盒内运行执行框架便于开发原型,但工作流编排与模型指导的任务执行也因此处在同一计算边界内。

执行框架可以在您的基础设施中运行,由沙盒在相应提供商的环境中执行有状态任务。

何时使用沙盒

如果智能体仅凭提示词上下文进行推理还不足以给出答案,需要在沙盒工作空间中实际执行任务,请使用沙盒。

常见情况包括:

  • 任务需要使用一整个目录的文档,单条提示词无法满足需要。
  • 智能体需要写入文件,以便您的应用稍后检查。
  • 智能体需要使用命令、软件包或脚本来完成工作。
  • 工作流会生成 Markdown、CSV、JSONL、屏幕截图或网站等产物。
  • 服务、笔记本或报告预览需要通过开放的端口提供访问。
  • 任务需要暂停以等待人工审核,然后在同一工作空间中继续。

如果您的工作流只需要模型给出简短回复,无需持久化工作空间,可以直接调用 Responses API,或使用不带沙盒的基础 Agents SDK 运行时。

如果只是偶尔需要访问 Shell,可以先使用使用工具中介绍的托管式 Shell 工具。如果产品设计要求隔离工作空间、选择沙盒提供商或恢复文件系统状态,请使用沙盒智能体。

沙盒带来的变化

SandboxAgent 仍然是一个 Agent,保留了常规智能体的接口,包括 instructions、prompt、tools、handoffs、MCP 服务器、模型设置、结构化输出、安全护栏和钩子。变化在于执行边界:运行器基于一个活动的沙盒会话为智能体做好运行准备。该会话管理文件、命令和端口,并提供相应提供商的隔离机制。

组成部分 职责 设计时需要考虑的问题
SandboxAgent 智能体定义及其沙盒默认设置 智能体应执行什么任务?它应自带哪些沙盒默认设置?
Manifest 约定新会话的初始工作空间 工作空间最初应包含哪些文件、目录、代码仓库、挂载项、环境设置、用户或用户组?
能力 为智能体添加沙盒原生行为 智能体需要哪些沙盒工具、指令或运行时行为?
沙盒客户端 对接提供商 活动工作空间应在哪里运行:Unix-local、Docker,还是托管提供商的环境?
沙盒会话 提供实际执行环境 在哪里运行命令、修改文件、开放端口和保存提供商状态?
沙盒运行配置 指定本次运行的沙盒会话来源、客户端选项和新会话输入 本次运行应传入已有沙盒会话、恢复会话,还是创建会话?
已保存的状态 RunState、序列化的会话状态和快照 后续运行应如何重新连接到已有工作空间,或用已有内容初始化新的工作空间?

沙盒专用的默认设置应放在 SandboxAgent 上。每次运行如何选择沙盒会话,则应在该次运行的沙盒配置中指定。

使用沙盒智能体时,一个轮次仍对应模型的一个步骤,单条 Shell 命令或单次沙盒操作并不单独算作一轮。有些工作可以完全在沙盒执行层内完成。只有在沙盒完成相关工作后还需要模型再次响应时,智能体运行时才会消耗新的轮次。

创建工作空间

Manifest 描述新沙盒工作空间所需的初始内容和布局。您可以用它指定智能体应能访问的文件、代码仓库、输入产物、辅助文件、挂载项和输出目录,并设置环境。

清单约定的是新会话的初始配置,无法完整反映每个活动沙盒的实际状态。一次运行实际使用的工作空间也可能来自复用的活动沙盒会话、序列化的沙盒会话状态,或运行时选定的快照。

清单条目的路径必须相对于工作空间,不能使用绝对路径,也不能通过 .. 跳出工作空间。这样,同一份工作空间配置就可以用于本地、Docker 和托管客户端。

清单输入 用途
File、Dir 创建小型合成输入、辅助文件或输出目录。
本地文件或目录 将主机上的文件或目录放入沙盒。
Git 代码仓库 将代码仓库拉取到工作空间中。
S3Mount、GCSMount、R2Mount、AzureBlobMount、BoxMount、S3FilesMount 在沙盒内提供对外部存储的访问。
environment 设置沙盒启动时需要的环境变量。
users 和 groups 对于支持预配账户的提供商,设置沙盒内的操作系统账户和用户组。

设计清单时,请遵循以下做法:

  • 将代码仓库、输入产物和输出目录列入清单。
  • 将较长的任务说明和代码仓库专用指令放在工作空间文件中,例如 repo/task.md 或 AGENTS.md。
  • 在指令中使用相对于工作空间的路径,例如 repo/task.md 或 output/report.md。
  • 将挂载存储的范围限定为智能体应读取或写入的输入。
  • 将挂载项视为临时工作空间条目。创建快照或持久化工作空间时,系统会跳过挂载的远程存储,不会将其内容复制到保存的工作空间中。

挂载文件和存储

所需的数据往往已存放在其他位置。您可以将大型文档挂载到沙盒中,让智能体直接处理文件,无需将文档粘贴到上下文中。

例如:

  • 挂载尽职调查资料室,让智能体生成注明出处的摘要。
  • 挂载导出的支持记录,让智能体将问题归类并整理成报告。
  • 挂载生成的产物,供其他系统审核。

各提供商的集成有各自的挂载辅助工具、凭据处理方式和持久化行为。应用应遵循一致的约定:只挂载智能体应使用的输入,告诉智能体在哪里读取和写入文件,并在使用生成的产物前进行检查。

处理密钥和凭据

请将沙盒凭据作为运行时配置提供,并与提示词内容分开。智能体可能需要使用凭据来访问软件包管理器、挂载的存储或提供商 API,但这些凭据不应出现在用户提示词、智能体指令、任务文件、提交到代码仓库的清单或生成的产物中。

请遵循以下规则:

  • 使用托管沙盒时,优先使用提供商原生的密钥管理系统。
  • 将云存储凭据的适用范围限定为需要这些凭据的挂载项或提供商选项。
  • 使用 Manifest.environment 指定沙盒进程启动时需要的值。对于敏感条目或自动生成的条目,如果您希望重新构建而非持久保存,请将其标记为临时条目。
  • 避免保存密钥、生成的挂载配置、本地令牌,以及运行结束后不应保留的文件。
  • 将产物移出沙盒之前,请先检查其内容,尤其是在智能体可以读取私有文档或挂载存储的情况下。

SDK 支持在清单中设置环境变量值,也支持使用提供商专用的挂载凭据。如何对接通用密钥存储取决于提供商。无论采用哪种方式,凭据都应由您的运行时或沙盒提供商注入,不应作为指令提供给模型。

为智能体添加能力

您可以通过能力为 SandboxAgent 添加沙盒原生行为。能力可以在运行开始前配置工作空间,追加沙盒专用指令,提供绑定到活动沙盒会话的工具,并调整该智能体的模型行为或输入处理方式。

能力 适用场景 说明
Shell 智能体需要访问 Shell。 支持执行命令。如果沙盒客户端支持,还可以使用交互式输入。
Filesystem 智能体需要编辑文件或查看本地图片。 提供 apply_patch 和 view_image。补丁路径相对于工作空间根目录。
Skills 您希望在沙盒中发现并加载技能文件。 优先使用此能力,无需手动挂载 .agents 或 .agents/skills。
Memory 后续运行需要读取或生成记忆文件。 需要 Shell。在运行期间更新记忆还需要 Filesystem。
Compaction 长时间运行的工作流需要裁剪上下文。 在出现压缩条目后调整模型行为和输入处理方式。

默认情况下,SandboxAgent 具备文件系统、Shell 和压缩能力。如果您传入 capabilities 列表,它会替换默认列表,因此请将智能体仍然需要的默认能力也列入其中。

如果内置能力可以满足需求,请优先使用。只有在您需要内置能力未涵盖的沙盒专用工具或指令接口时,才需要编写自定义能力。

加载技能

有些任务需要在智能体启动前准备可重复使用的指令、脚本、参考资料或资源。使用 Skills 能力,智能体就能在运行期间找到这些资料和资源。

加载技能
import {
  Capabilities,
  SandboxAgent,
  gitRepo,
  skills,
} from "@openai/agents/sandbox";

const agent = new SandboxAgent({
  name: "Tax prep assistant",
  instructions: "Use the mounted skill before preparing the return.",
  capabilities: [
    ...Capabilities.default(),
    skills({
      from: gitRepo({
        repo: "owner/tax-prep-skills",
        ref: "main",
      }),
    }),
  ],
});

根据技能文件的加载方式选择技能来源:

  • 对于较大的本地技能目录,如果您希望模型先查看索引,再按需加载内容,请使用延迟加载的本地目录作为来源。
  • 对于较小的本地技能包,可以使用本地目录作为来源,预先加载整个技能包。
  • 如果技能包有独立的发布周期,或有多个沙盒需要使用它,请使用 Git 代码仓库作为来源。

对外提供预览和开放端口

有时,智能体的产物是一个运行中的进程。当智能体创建了本地应用、笔记本、报告服务器、浏览器预览或其他服务,而您需要在沙盒外查看时,请开放端口。

各提供商设置端口的方式不同,但产品层面的约定一致:智能体在沙盒内启动服务,沙盒客户端开放端口,您的应用则分享生成的预览 URL 或通过该 URL 查看预览。

运行沙盒智能体

最简单的沙盒运行流程包括以下步骤:

  1. 创建描述工作空间的 Manifest。
  2. 创建 SandboxAgent,并为其添加模型所需的能力。
  3. 根据任务应运行的环境选择沙盒客户端。
  4. 使用本次运行的沙盒配置来运行智能体。
  5. 检查或复制应用需要的产物、恢复相关工作,或创建快照。

在 macOS 或 Linux 上进行本地开发时,可以先使用 Unix-local。运行器可以根据智能体的默认清单创建临时工作空间,并在运行结束后自动清理,因此本地运行流程很简单。

如果使用 TypeScript SDK,请先在主机上安装可信的 Python 3 解释器,再使用 UnixLocalSandboxClient 创建会话。SDK 使用 Python 以受保护的方式访问本地文件,并会在 /usr/bin/python3、/usr/local/bin/python3 和 /opt/homebrew/bin/python3 这三个位置查找解释器。如果 Python 安装在其他位置,请在启动 Node.js 之前,将主机环境变量 OPENAI_AGENTS_PYTHON 设置为 Python 可执行文件的绝对路径。此项要求针对主机,无需在沙盒内安装 Python。如果没有可用的合适 Python 解释器,会话创建将失败。

运行 Unix-local 沙盒智能体
import { run } from "@openai/agents";
import { Manifest, SandboxAgent, file, shell } from "@openai/agents/sandbox";
import { UnixLocalSandboxClient } from "@openai/agents/sandbox/local";

const manifest = new Manifest({
  entries: {
    "account_brief.md": file({
      content:
        "# Northwind Health\n\n" +
        "- Segment: Mid-market healthcare analytics provider.\n" +
        "- Renewal date: 2026-04-15.\n",
    }),
    "implementation_risks.md": file({
      content:
        "# Delivery risks\n\n" +
        "- Security questionnaire is not complete.\n" +
        "- Procurement requires final legal language by April 1.\n",
    }),
  },
});

const agent = new SandboxAgent({
  name: "Renewal Packet Analyst",
  model: "gpt-6.2-astra",
  instructions:
    "Review the workspace before answering. Keep the response concise, " +
    "business-focused, and cite the file names that support each conclusion.",
  defaultManifest: manifest,
  capabilities: [shell()],
});

const result = await run(
  agent,
  "Summarize the renewal blockers and recommend the next two actions.",
  {
    sandbox: {
      client: new UnixLocalSandboxClient(),
    },
  }
);

console.log(result.finalOutput);

完整的本地示例见 TypeScript 沙盒智能体快速入门和 Python unix_local_runner.py。

切换提供商

提供商由运行配置指定。您可以沿用原有的 SandboxAgent、清单和能力,只需根据目标环境更换沙盒客户端和提供商选项。

本示例使用 Docker 在本地实现容器隔离。托管提供商也采用相同的方式,只是使用各自的客户端类和选项。

切换到 Docker
import { run } from "@openai/agents";
import { SandboxAgent } from "@openai/agents/sandbox";
import { DockerSandboxClient } from "@openai/agents/sandbox/local";

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

const result = await run(agent, "Inspect the workspace.", {
  sandbox: {
    client: new DockerSandboxClient({
      image: "node:22-bookworm-slim",
    }),
  },
});

console.log(result.finalOutput);

如需可运行的示例,请参阅 TypeScript 沙盒客户端指南和基础示例。SDK 代码仓库中还提供了 Python 示例:basic.py 演示如何选择提供商,docker_runner.py 演示如何使用 Docker,main.py 演示资料室工作流。

进阶用法

基本流程运行起来后,您可以将沙盒用于这样的工作流:智能体需要实际操作工作空间,仅增加提示词上下文无法满足任务要求。以下示例展示了同一套 API 支持的不同工作流模式。同一个执行框架可以负责工作流的路由、暂停、恢复和追踪,各沙盒则在所需文件、工具和端口所在的环境中执行任务。

示例 说明
资料室问答 根据挂载的资料室中的内容回答问题。
从资料室提取表格 从挂载的资料室中提取表格。
代码仓库审查 克隆并检查代码仓库,生成代码审查产物。
使用视觉能力复刻网站 使用 Vision API 和屏幕截图反馈复刻网站。
恢复沙盒工作 在已有沙盒中继续工作。

恢复工作或为后续运行设置初始状态

智能体的任务经常需要跨多个请求完成:用户可能需要审核产物,某个步骤可能需要审批,或者下一步可能需要等待之后发生的事件。

请区分以下三种状态:

状态类型 恢复的内容 适用场景
RunState 执行框架侧的状态,例如模型条目、工具状态、审批信息,以及当前活动智能体在工作流中的位置。 运行器需要在暂停后继续推进工作流。
会话状态 已序列化的沙盒会话,客户端可据此重新连接到该会话。 您的应用或作业系统直接存储提供商的会话状态。
snapshot 已保存的工作空间内容,用于初始化新的沙盒会话。 新的运行需要从已保存的文件和产物开始,而非从空工作空间开始。

运行器按以下顺序确定使用哪个沙盒会话:

  1. 如果您传入活动沙盒会话,运行器会直接复用该会话。
  2. 否则,如果本次运行正从 RunState 恢复,运行器会根据其中保存的沙盒会话状态恢复会话。
  3. 否则,如果您显式传入了序列化的沙盒状态,运行器会从该状态恢复会话。
  4. 如果以上条件都不满足,运行器会创建新的沙盒会话。如果您为本次运行提供了清单,新会话会使用该清单,否则会使用智能体的默认清单。

下面的沙盒恢复示例先将已停止会话的状态序列化,再通过同一客户端恢复会话,并将恢复的会话传入下一次运行:

序列化并恢复沙盒状态
import { run } from "@openai/agents";
import { Manifest, SandboxAgent } from "@openai/agents/sandbox";
import { UnixLocalSandboxClient } from "@openai/agents/sandbox/local";

const manifest = new Manifest();
const client = new UnixLocalSandboxClient({
  snapshot: { type: "local", baseDir: "/tmp/my-sandbox-snapshots" },
});
const agent = new SandboxAgent({
  name: "Workspace builder",
  model: "gpt-6.2-astra",
  instructions: "Inspect the sandbox workspace before answering.",
});

const session = await client.create({ manifest });
let conversation = [];
let frozenSessionState;

try {
  const firstResult = await run(agent, "Build the first version of the app.", {
    maxTurns: 20,
    sandbox: { session },
  });

  conversation = firstResult.history;
  frozenSessionState = await client.serializeSessionState?.(session.state);
} finally {
  await session.close?.();
}

if (!frozenSessionState || !client.deserializeSessionState || !client.resume) {
  throw new Error("Sandbox client does not support session resume.");
}

const resumedSession = await client.resume(
  await client.deserializeSessionState(frozenSessionState)
);

try {
  conversation.push({
    role: "user",
    content: "Continue from the existing workspace and add tests.",
  });

  const secondResult = await run(agent, conversation, {
    maxTurns: 20,
    sandbox: { session: resumedSession },
  });
  console.log(secondResult.finalOutput);
} finally {
  await resumedSession.close?.();
}

manifest 和 snapshot 等新会话输入仅在运行器创建新沙盒会话时生效。如果您传入活动的 session,在处理智能体能力时可以添加兼容的非挂载条目,但不能更改根目录、环境、用户或用户组,不能移除已有条目或替换条目类型,也不能在已经运行的沙盒中添加或修改挂载项。

这样分工后,执行框架负责恢复智能体循环,沙盒提供商则负责恢复或重新创建工作空间。有关这些流程的最新示例代码,请参阅 TypeScript 恢复会话状态示例,以及 Python 的 main.py 和 sandbox_agent_with_remote_snapshot.py。

跨运行保留记忆

沙盒记忆让沙盒智能体能在后续运行中利用以往的经验。它与 SDK 管理的对话 Session 记忆各自独立:对话会话保留消息历史,而沙盒记忆会从之前在工作空间中执行的任务里提炼有用的经验,写入文件供智能体日后读取。

如果智能体需要沿用用户偏好、更正内容、特定项目的经验或任务摘要,又无需重放此前的每一轮交互,请使用记忆。会话恢复和快照保留的是工作空间状态,记忆保留的是从工作空间中已完成的任务里总结出的可复用指导。

启用沙盒记忆
import {
  Manifest,
  SandboxAgent,
  filesystem,
  memory,
  shell,
} from "@openai/agents/sandbox";

const manifest = new Manifest();

const agent = new SandboxAgent({
  name: "Memory-enabled reviewer",
  instructions:
    "Inspect the workspace and retain useful lessons for follow-up runs.",
  defaultManifest: manifest,
  capabilities: [memory(), filesystem(), shell()],
});

默认情况下,记忆功能同时启用读取和生成。读取记忆需要 Shell 访问权限,以便智能体搜索并打开记忆文件。默认情况下,在运行期间更新记忆还需要文件系统访问权限,以便智能体修正过时的记忆,或根据用户要求更新记忆。

智能体按需逐步读取记忆。SDK 会在运行开始时注入 memory_summary.md。如果之前的工作可能与当前任务有关,智能体就会搜索 MEMORY.md,只有在需要了解更多细节时才打开相应的运行摘要。

记忆模式 适用场景
默认读写 智能体需要读取已有记忆并生成新记忆。
只读记忆 智能体应读取记忆,但不应在运行结束后生成新记忆。
仅生成记忆 本次运行应生成新记忆,且不使用已有记忆。
读取配置 您需要禁用运行期间的记忆更新。
生成配置 您需要调整记忆生成方式,例如设置额外的提示词。
布局配置 同一沙盒工作空间中的多个智能体需要各自独立的记忆目录布局。

默认情况下,记忆产物存放在沙盒工作空间中:

workspace/
  sessions/
    <rollout-id>.jsonl
  memories/
    memory_summary.md
    MEMORY.md
    raw_memories.md
    phase_two_selection.json
    raw_memories/
      <rollout-id>.md
    rollout_summaries/
      <rollout-id>_<slug>.md
    skills/

运行时会在沙盒会话期间追加运行片段。会话关闭时,记忆生成流程先提取对话摘要和原始记忆,再将这些原始记忆整合到 MEMORY.md 和 memory_summary.md 中。要在后续运行中复用记忆,请保留已配置的记忆目录。您可以继续使用同一个活动沙盒会话、从会话状态恢复、从快照启动,或挂载 S3 等持久化存储。

进行多轮沙盒对话时,请持续使用同一个 SDK 会话,并搭配同一个活动沙盒会话。记忆功能按以下优先顺序选取 ID 来对运行分组:显式指定的对话 ID、SDK 会话 ID、运行组 ID,最后才是为每次运行生成的 ID。沙盒会话 ID 标识活动工作空间,与记忆功能使用的对话 ID 不同。

如需可运行的示例,请参阅 TypeScript 记忆指南。Python 示例中,memory.py 演示本地快照流程,memory_s3.py 演示如何使用 S3 存储记忆,memory_multi_agent_multiturn.py 演示如何为不同智能体设置独立的记忆目录布局。

组合使用沙盒智能体

沙盒智能体可以与 SDK 的其他功能配合使用。

如果负责接收任务的智能体在沙盒外运行,并且只需把工作流中需要大量操作工作空间的部分委托给沙盒智能体,请使用任务移交。顶层运行会继续进行,沙盒智能体则成为下一轮的活动智能体。

如果外层编排器需要将一个或多个沙盒智能体作为嵌套工具调用,请使用智能体作为工具。每个作为工具调用的沙盒智能体都可以有自己的沙盒运行配置、沙盒客户端、清单和提供商选项。

示例见 handoffs.py 和 sandbox_agents_as_tools.py。

沙盒提供商

要在本地快速迭代,可以先使用 Unix-local。如果需要本地容器隔离,请使用 Docker。如果任务需要托管执行、提供商特有的隔离机制、扩缩容、预览、存储挂载或快照,或者需要将凭据保存在应用服务器之外,请改用托管提供商。

有关各提供商的配置、凭据、隔离、存储、预览和持久化行为,请参阅相应提供商的文档。

提供商 SDK 客户端 文档和示例
Blaxel BlaxelSandboxClient 沙盒概览
Cloudflare CloudflareSandboxClient 沙盒文档
OpenAI 智能体教程
Sandbox Bridge 示例
Databricks DatabricksSandboxClient 如果使用 Python,请安装 databricks-openai[sandbox]。
沙盒文档
OpenAI Agents SDK 示例
Databricks SDK for Python 指南
Daytona DaytonaSandboxClient 沙盒文档
OpenAI Agents SDK 指南
Docker DockerSandboxClient Docker 文档
在 TypeScript SDK 中使用 Docker 的示例
在 Python SDK 中使用 Docker 的示例
E2B E2BSandboxClient 沙盒文档
OpenAI Agents SDK 指南
发布公告
Modal ModalSandboxClient 沙盒指南
集成介绍
示例代码仓库
Modal 扩展参考文档
Unix-local UnixLocalSandboxClient 在本地运行 TypeScript SDK 的示例
在本地运行 Python SDK 的示例
Vercel VercelSandboxClient 沙盒文档
OpenAI Agents SDK 指南
FastAPI 模板
示例应用