快速入门

现代智能体只有能够操作文件系统中的真实文件，才能发挥最佳效果。Agents SDK 中的沙盒智能体为模型提供持久化工作区，使其能够搜索大型文档集、编辑文件、运行命令、生成产物，并基于已保存的沙盒状态继续工作。

SDK 提供了这套执行框架，无需您自行整合文件暂存、文件系统工具、Shell 访问、沙盒生命周期、快照以及特定于提供商的适配代码。您可以继续使用常规的 Agent 和 Runner 流程，然后为工作区添加 Manifest，为沙盒原生工具添加能力，并通过 sandbox 运行选项指定工作执行的位置。

前提条件

Node.js 22 或更高版本。
基本熟悉 OpenAI Agents SDK。
一个沙盒客户端。在 macOS 或 Linux 上进行本地开发时，建议从 UnixLocalSandboxClient 开始。在 Windows 上，请改用 DockerSandboxClient 或托管沙盒客户端。

本快速开始使用 Node.js 和 npm 命令，但 SDK 并不局限于 Node.js。如果项目使用兼容的软件包解析方式和运行时 API，沙盒智能体也可以在 Deno 和 Bun 上运行。

安装

如果您尚未安装 SDK：

npm install @openai/agents

对于由 Docker 支持的沙盒，请在本地安装 Docker，并使用 @openai/agents/sandbox/local 中的 DockerSandboxClient。

如果您通过 tty: true 使用交互式本地 PTY 会话，运行 SDK 的进程还需要能够通过 python3 或 OPENAI_AGENTS_PYTHON 使用 Python 3。非 PTY Shell 命令不需要 Python。

本地沙盒智能体的创建

此示例将本地仓库暂存到 repo/ 下，延迟加载本地技能，并允许运行器为本次运行创建 Unix 本地沙盒会话。智能体定义负责管理清单和能力，而运行配置仅为本次运行选择沙盒客户端。

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);

关键选项

基本运行正常后，大多数人接下来通常会使用以下选项：

defaultManifest：新沙盒会话所需的文件、仓库、目录和挂载项。
instructions：应在不同提示中统一应用的简短工作流规则。
baseInstructions：用于替换 SDK 沙盒提示的高级应急选项。
capabilities：沙盒原生工具，例如文件系统编辑、图像检查、Shell、技能、记忆和压缩。
runAs：面向模型的工具所使用的沙盒用户身份。
sandbox.client：沙盒后端。
sandbox.session、sandbox.sessionState 或 sandbox.snapshot：后续运行如何重新连接到之前的工作。

后续步骤

概念：了解清单、能力、权限、快照、运行配置和组合模式。
沙盒客户端：选择 Unix 本地、Docker、托管提供商以及挂载策略。
智能体记忆：保留并复用之前沙盒运行中获得的经验。

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