快速入门

现代智能体在能够操作文件系统中的真实文件时表现最佳。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 本地沙盒会话。清单和能力配置由智能体定义负责，而运行配置仅选择本次运行使用的沙盒客户端。

UnixLocalSandboxClient 在 macOS 和 Linux 上均以宿主机进程的形式运行命令。该客户端不提供操作系统级的文件系统或网络隔离。请仅将此示例用于可信的本地开发，或在外部隔离环境中使用。对于不可信的命令（包括受不可信输入影响的命令），请选择配置适当的 Docker 或托管后端，或提供外部隔离。请参阅 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 开始。当工作区管理、沙盒客户端选择或沙盒会话恢复行为属于设计的一部分时，再选择沙盒智能体。