快速入门

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

SDK 为您提供了这套执行基础设施，无需您自己拼装文件暂存、文件系统工具、shell 访问、沙盒生命周期、快照以及特定提供方的粘合逻辑。您仍然沿用常规的 Agent 和 Runner 流程，然后添加工作区的 Manifest、用于沙盒原生工具的 capabilities，以及用于指定工作运行位置的 sandbox 运行选项。

前提条件

Node.js 22 或更高版本。
对 OpenAI Agents SDK 有基本了解。
一个沙盒客户端。对于本地开发，建议从 UnixLocalSandboxClient 开始。

本 quickstart 使用 Node.js 和 npm 命令，但 SDK 并不局限于 Node.js。只要项目使用兼容的包解析和运行时 API，Sandbox agent 也可以在 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/ 下，按需延迟加载本地 skills，并让 runner 为本次运行创建一个 Unix 本地沙盒会话。智能体定义拥有 manifest 和 capabilities，而运行配置仅为本次运行选择沙盒客户端。

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(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、skills、记忆和压缩。
runAs：面向模型的工具所使用的沙盒用户身份。
sandbox.client：沙盒后端。
sandbox.session、sandbox.sessionState 或 sandbox.snapshot：后续运行如何重新连接到先前的工作。

后续内容

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

如果 shell 访问只是偶尔使用的一种工具，请先从工具指南中的托管 shell 开始。如果您的设计需要工作区隔离、沙盒客户端选择或沙盒会话恢复行为，请使用沙盒智能体。