OpenAI Agents SDK 沙箱智能体

沙箱为智能体提供隔离的类Unix执行环境，包含文件系统、shell、已安装软件包、挂载数据、对外开放的端口、快照，以及对外部系统的受控访问。

当模型需要这类工作区，却只拿到提示词上下文时，工作流容易变得脆弱。大型文档集、生成产物、命令、预览及可恢复工作，都需要智能体可以检查和修改的环境。

TypeScript和Python版Agents SDK均支持沙箱智能体。本页讨论由应用运行执行框架的SDK沙箱；OpenAI管理执行框架的方案见Agents API：连接沙箱。

需要操作文件、运行命令、挂载资料室、生成产物、开放服务或稍后继续有状态工作时，可以使用沙箱。

关键是区分执行框架与计算资源。执行框架是围绕模型的控制平面，负责智能体循环、模型调用、工具路由、交接、批准、追踪、恢复和运行状态；计算资源是沙箱执行平面，负责按模型要求读写文件、执行命令、安装依赖、访问挂载存储、开放端口及创建状态快照。

分开边界后，应用可以把敏感控制工作留在可信基础设施中，沙箱专注于提供商特有的执行。沙箱使用范围有限的凭证和挂载操作文件；执行框架则把认证、计费、审计日志、人工审查与恢复状态保存在单个容器之外。

在沙箱中运行执行框架便于开发原型，但编排与模型引导的执行会处于同一计算边界。

执行框架可以运行在自有基础设施中，由沙箱处理提供商特有的有状态执行。

何时使用沙箱

答案依赖工作区中的实际操作，而非只对提示词上下文进行推理时，使用沙箱。常见需求包括：

• 输入是一整个文档目录，而非单条提示词。
• 智能体需要写出可供应用稍后检查的文件。
• 完成工作需要命令、软件包或脚本。
• 工作流生成Markdown、CSV、JSONL、截图或网站等产物。
• 服务、笔记本或报告预览需要开放端口。
• 等待人工审查后，需要在同一工作区继续。

只需要简短模型响应、无需持久工作区时，可直接调用Responses API，或使用不带沙箱的基础Agents SDK运行时。

只是偶尔需要shell工具时，先看使用工具中的托管shell。工作区隔离、提供商选择或可恢复文件系统状态属于产品设计时，再使用沙箱智能体。

沙箱增加了什么

SandboxAgent仍然是Agent，保留instructions、prompt、tools、handoffs、MCP服务器、模型设置、结构化输出、护栏和钩子。变化在于执行边界：runner将智能体与活动沙箱会话连接，由该会话负责文件、命令、端口与提供商隔离。

沙箱特有默认设置放在SandboxAgent中，单次运行的沙箱会话选择放在运行的沙箱配置中。

沙箱智能体不会改变轮次的含义：这里的轮次仍是一个模型步骤，而非单条shell命令或沙箱操作。有些工作留在沙箱执行层，只有沙箱操作后需要新的模型响应时，智能体运行时才消耗另一个轮次。

创建工作区

Manifest描述新沙箱工作区期望的初始内容与布局，包括文件、仓库、输入产物、辅助文件、挂载、输出目录和环境准备。

应把清单视为新建会话约定，不是每个活动沙箱的完整事实来源。一次运行的实际工作区也可能来自复用的活动会话、序列化会话状态，或运行时选择的快照。

条目路径相对工作区，不能是绝对路径，也不能通过..越出工作区，使配置可在本地、Docker和托管客户端之间移植。

设计清单时，把仓库、输入产物与输出目录放进清单；较长任务说明和仓库本地指令写入repo/task.md或AGENTS.md等文件；指令使用repo/task.md、output/report.md等相对路径；挂载范围只覆盖智能体应读写的数据。挂载条目是临时工作区条目，快照与持久化流程会跳过挂载的远程存储，而非将其复制到保存的工作区内容中。

挂载文件与存储

有用数据往往已经存放在其他系统。与其把大文档粘贴到上下文，不如挂载进沙箱，让智能体通过文件处理。例如挂载尽调资料室并生成带引用摘要，挂载支持记录导出并聚类成报告，或挂载生成产物供另一系统审查。

各提供商有不同挂载辅助接口、凭证处理和持久化行为，但应用约定保持一致：只挂载必要输入，告诉智能体读写位置，使用生成产物前先检查。

处理秘密与凭证

沙箱凭证属于运行时配置，不属于提示词内容。智能体可能需要软件包管理器、存储挂载或提供商API的访问凭证，但这些值不应出现在用户提示词、智能体指令、任务文件、已提交清单或生成产物中。

• 托管提供商优先使用其原生秘密管理系统。
• 云存储凭证只放在需要它的挂载或提供商选项范围内。
• Manifest.environment保存沙箱进程启动所需值。希望重新生成而非持久保存的敏感或生成条目，应标记为临时条目（ephemeral）。
• 避免保存秘密、生成的挂载配置、本地令牌或不应跨运行保留的文件。
• 产物移出沙箱前先审查，尤其是智能体能读取私有文档或挂载存储时。

SDK支持清单环境值及提供商专属挂载凭证。通用秘密存储集成因提供商而异，核心约定是由运行时或提供商注入凭证，而非作为指令教给模型。

为智能体添加能力

能力为SandboxAgent附加沙箱原生行为：运行前准备工作区、追加沙箱指令、提供绑定活动会话的工具，并调整模型行为或输入处理。

SandboxAgent默认包含文件系统、shell和压缩能力。显式提供capabilities列表会替换整个默认列表，仍需要的默认能力应自行列入。

内置能力适用时优先使用；只有内置能力未覆盖的沙箱工具或指令需求，才编写自定义能力。

加载技能

一些任务需要可重复使用的指令、脚本、参考资料或素材。通过Skills能力，使智能体在运行中发现这些工作上下文：

来源示例 1（javascript）：

// [中文] 示例1：加载技能。
// [中文] 技能源是示意仓库owner/tax-prep-skills的main分支；实际运行时换成可访问的技能仓库。
// [中文] 报税准备助手的指令是“准备申报前先使用挂载技能”；把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",
      }),
    }),
  ],
});

来源示例 2（python）：

## [中文] 示例2：加载技能。
## [中文] 技能源是示意仓库owner/tax-prep-skills的main分支；实际运行时换成可访问的技能仓库。
## [中文] 报税准备助手的指令是“准备申报前先使用挂载技能”；把Skills加到默认能力，而非丢弃默认列表。
from agents.sandbox import SandboxAgent
from agents.sandbox.capabilities import Capabilities, Skills
from agents.sandbox.entries import GitRepo

agent = 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。

运行沙箱智能体

最小有效流程是：创建描述工作区的Manifest；创建包含所需能力的SandboxAgent；选择执行位置对应的沙箱客户端；以单次运行的沙箱配置运行；检查、复制、恢复或快照保存应用所需产物。

macOS或Linux本地开发可从Unix-local开始。runner能够根据智能体默认清单创建临时工作区，运行后清理，形成最小本地循环。

来源示例 3（javascript）：

使用TypeScript SDK的 UnixLocalSandboxClient 创建会话前，须在宿主机安装可信的Python 3解释器。SDK通过Python保护本地文件访问，并检查 /usr/bin/python3、/usr/local/bin/python3 和 /opt/homebrew/bin/python3。Python位于其他位置时，在启动Node.js前将宿主环境变量 OPENAI_AGENTS_PYTHON 设为解释器的绝对路径。这是宿主机前置条件，不是在沙箱内部安装的软件包；找不到合适解释器时，会话创建失败。

// [中文] 示例3：运行沙箱智能体。
// [中文] 清单创建两个虚构业务输入：Northwind Health是中型医疗分析提供商，续约日期2026-04-15；安全问卷未完成，采购要求4月1日前确定最终法律文本。
// [中文] 指令要求先检查工作区，简洁面向业务作答并引用支持结论的文件名；输入要求总结续约阻碍并推荐接下来的两项行动。
// [中文] Unix-local客户端按默认清单准备工作区；显式能力列表只有Shell，不宣称仍包含全部默认能力。
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-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);

来源示例 4（python）：

## [中文] 示例4：运行沙箱智能体。
## [中文] 清单创建两个虚构业务输入：Northwind Health是中型医疗分析提供商，续约日期2026-04-15；安全问卷未完成，采购要求4月1日前确定最终法律文本。
## [中文] 指令要求先检查工作区，简洁面向业务作答并引用支持结论的文件名；输入要求总结续约阻碍并推荐接下来的两项行动。
## [中文] Unix-local客户端按默认清单准备工作区；显式能力列表只有Shell，不宣称仍包含全部默认能力。
import asyncio

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Shell
from agents.sandbox.entries import File
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

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

agent = SandboxAgent(
    name="Renewal Packet Analyst",
    model="gpt-6-astra",
    instructions=(
        "Review the workspace before answering. Keep the response concise, "
        "business-focused, and cite the file names that support each conclusion."
    ),
    default_manifest=manifest,
    capabilities=[Shell()],
)


async def main():
    result = await Runner.run(
        agent,
        "Summarize the renewal blockers and recommend the next two actions.",
        run_config=RunConfig(
            sandbox=SandboxRunConfig(client=UnixLocalSandboxClient()),
            workflow_name="Unix-local sandbox review",
        ),
    )
    print(result.final_output)


asyncio.run(main())

完整本地示例见TypeScript沙箱快速开始及Python的unix_local_runner.py。

切换提供商

提供商属于运行配置，不是智能体定义。保持SandboxAgent、清单和能力不变，替换客户端与提供商选项。

下例切换到Docker进行本地容器隔离；托管提供商使用各自客户端类和选项，但遵循相同模式：

来源示例 5（javascript）：

// [中文] 示例5：切换提供商。
// [中文] 切换到Docker客户端；JavaScript选择node:22-bookworm-slim镜像，指令及输入要求先检查工作区。
// [中文] Python复用前文agent，并使用默认Python沙箱镜像，任务仍是总结续约阻碍并推荐两项行动；这是依赖前文变量的异步片段，需要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-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);

来源示例 6（python）：

## [中文] 示例6：切换提供商。
## [中文] 切换到Docker客户端；JavaScript选择node:22-bookworm-slim镜像，指令及输入要求先检查工作区。
## [中文] Python复用前文agent，并使用默认Python沙箱镜像，任务仍是总结续约阻碍并推荐两项行动；这是依赖前文变量的异步片段，需要Docker环境。
## [中文] network_mode="none"禁用此Docker沙箱网络；完成后打印final_output，仍依赖前文异步上下文。
from docker import from_env as docker_from_env

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxRunConfig
from agents.sandbox.config import DEFAULT_PYTHON_SANDBOX_IMAGE
from agents.sandbox.sandboxes.docker import (
    DockerSandboxClient,
    DockerSandboxClientOptions,
)

docker_run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=DockerSandboxClient(docker_from_env()),
        options=DockerSandboxClientOptions(
            image=DEFAULT_PYTHON_SANDBOX_IMAGE,
            network_mode="none",
        ),
    ),
    workflow_name="Docker sandbox review",
)

result = await Runner.run(
    agent,
    "Summarize the renewal blockers and recommend the next two actions.",
    run_config=docker_run_config,
)

print(result.final_output)

可运行示例见TypeScript客户端指南和基础示例；Python的basic.py展示提供商选择，docker_runner.py展示Docker，main.py展示资料室流程。

进阶模式

基本循环运行后，可构建真正依赖工作区而非更多提示词上下文的流程。这些是工作流模式，不是独立API；相同执行框架仍可路由、暂停、恢复和追踪，各沙箱把执行放在所需文件、工具与端口附近。

恢复工作或初始化后续工作

有用工作往往超过一个请求：用户需要审查产物、某个步骤等待批准，或下一步取决于之后的事件。

runner按以下顺序确定沙箱会话：

1. 已传入活动会话时，直接复用。
2. 否则，若从RunState恢复，使用其中保存的沙箱会话状态。
3. 否则，若显式传入序列化沙箱状态，从该状态恢复。
4. 否则创建新会话；新会话优先使用单次运行清单，未提供时使用智能体默认清单。

下例序列化已停止会话状态，经同一客户端恢复，再把恢复后的会话传入下一次运行：

来源示例 7（javascript）：

// [中文] 示例7：恢复工作或初始化后续工作。
// [中文] 第一轮要求“构建应用第一版”，保存对话历史与序列化会话状态；第二轮要求“基于现有工作区继续并添加测试”。
// [中文] 会话经同一客户端恢复，运行最多20个模型轮次；RunState、对话历史与沙箱会话状态不是同一资源。
// [中文] JavaScript最终关闭会话；Python最终删除恢复的沙箱会话，且依赖前文agent、client、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 client = new UnixLocalSandboxClient({
  snapshot: { type: "local", baseDir: "/tmp/my-sandbox-snapshots" },
});
const agent = new SandboxAgent({
  name: "Workspace builder",
  model: "gpt-6-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?.();
}

来源示例 8（python）：

## [中文] 示例8：恢复工作或初始化后续工作。
## [中文] 第一轮创建app.py中的加法函数并验证2+3=5，保存对话与会话状态；第二轮读取原文件，添加正数和负数两项unittest测试并运行。
## [中文] 会话经同一客户端恢复，运行最多20个模型轮次；RunState、对话历史与沙箱会话状态不是同一资源。
## [中文] JavaScript最终关闭会话；Python最终删除恢复的沙箱会话，且依赖前文agent、client、session等变量，不能直接当成完整独立脚本。
async with session:
    first_result = await Runner.run(
        agent,
        "Create app.py with an add(a, b) function that returns their sum. "
        "Run it once to check that add(2, 3) equals 5.",
        max_turns=20,
        run_config=RunConfig(
            sandbox=SandboxRunConfig(session=session),
            workflow_name="Sandbox resume example",
        ),
    )

conversation = first_result.to_input_list()
frozen_session_state = client.deserialize_session_state(
    client.serialize_session_state(session.state)
)

conversation.append(
    {
        "role": "user",
        "content": (
            "Read the existing app.py without replacing it. Add test_app.py with "
            "two unittest tests: one for positive inputs and one for negative "
            "inputs. Run both tests."
        ),
    }
)

resumed_session = await client.resume(frozen_session_state)
try:
    async with resumed_session:
        second_result = await Runner.run(
            agent,
            conversation,
            max_turns=20,
            run_config=RunConfig(
                sandbox=SandboxRunConfig(session=resumed_session),
                workflow_name="Sandbox resume example",
            ),
        )
finally:
    await client.delete(resumed_session)

print(second_result.final_output)

manifest、snapshot等新建输入只在runner创建新沙箱会话时生效。注入活动session时，能力处理可以增加兼容的非挂载条目，但不能改变根目录、环境、用户或组，不能移除已有条目、替换条目类型，也不能新增或修改挂载。

这种分工让执行框架恢复循环，由提供商恢复或重建工作区。现有示例见TypeScript恢复会话状态，以及Python的main.py和sandbox_agent_with_remote_snapshot.py。

跨运行持久保存记忆

沙箱记忆让后续运行从既往工作中学习。它不同于SDK会话Session保存的对话记忆：会话保存消息历史，沙箱记忆将工作经验提炼为之后可读的文件。

需要延续用户偏好、纠正、项目经验或任务摘要，又不想重放每个旧轮次时，可以使用记忆。恢复和快照保留工作区状态，记忆则保留可复用的工作指导。

来源示例 9（javascript）：

// [中文] 示例9：跨运行持久保存记忆。
// [中文] 记忆审查助手的指令是“检查工作区，并保留对后续运行有用的经验”；显式配置Memory、Filesystem和Shell。
// [中文] 本段只创建智能体配置，没有执行运行或已经生成记忆；后续复用需保存相应目录或会话状态。
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()],
});

来源示例 10（python）：

## [中文] 示例10：跨运行持久保存记忆。
## [中文] 记忆审查助手的指令是“检查工作区，并保留对后续运行有用的经验”；显式配置Memory、Filesystem和Shell。
## [中文] 本段只创建智能体配置，没有执行运行或已经生成记忆；后续复用需保存相应目录或会话状态。
from agents.sandbox.capabilities import Filesystem, Memory, Shell

agent = SandboxAgent(
    name="Memory-enabled reviewer",
    instructions="Inspect the workspace and retain useful lessons for follow-up runs.",
    default_manifest=manifest,
    capabilities=[Memory(), Filesystem(), Shell()],
)

记忆默认同时启用读取和生成。读取需要shell，以搜索和打开文件；默认实时更新还需要文件系统访问，以修复过时记忆或按用户要求更新。

读取采用渐进披露：SDK在运行开始注入memory_summary.md，既往工作相关时，智能体搜索MEMORY.md，只有需要细节时才打开运行摘要。

默认记忆产物位于工作区：

来源示例 11（text）：

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、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。需要托管执行、提供商特有隔离、扩缩容、预览、存储挂载、快照，或凭证不应留在应用服务器时，可选择托管提供商。

具体配置、凭证、隔离、存储、预览及持久化行为见各提供商文档。