快速入门

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

SDK 为你提供这套执行框架，无需你自行串联文件暂存、文件系统工具、shell 访问、沙盒生命周期、快照以及特定提供商的衔接逻辑。你可以保留常规的 Agent 和 Runner 流程，然后为工作区添加 Manifest、为沙盒原生工具添加能力，并通过 sandbox 运行选项指定工作运行的位置。

前提条件

Node.js 22 或更高版本。
基本熟悉 OpenAI Agents SDK。
一个沙盒客户端。对于本地开发，请从 UnixLocalSandboxClient 开始。

本快速开始使用 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 的进程还需要提供可用的 Python 3（以 python3 的形式，或通过 OPENAI_AGENTS_PYTHON）。非 PTY shell 命令不需要 Python。

本地沙盒智能体的创建

此示例会将本地仓库暂存到 repo/ 下，按需延迟加载本地技能，并让 runner 为本次运行创建一个 Unix 本地沙盒会话。智能体定义拥有 manifest 和能力，而运行配置只为本次运行选择沙盒客户端。

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.5',
  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：后续运行如何重新连接到之前的工作。

后续步骤

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

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