クイックスタート

最新のエージェントは、ファイルシステム上の実際のファイルを操作できるときに、その能力を最大限に発揮します。Agents SDK の サンドボックスエージェント は、モデルに永続的なワークスペースを提供します。ここでは、大量のドキュメントの検索、ファイルの編集、コマンドの実行、成果物の生成、保存したサンドボックスの状態からの作業再開が可能です。

SDK はこの実行基盤を提供するため、ファイルの配置、ファイルシステムツール、シェルアクセス、サンドボックスのライフサイクル、スナップショット、プロバイダー固有の連携処理を自分で組み合わせる必要はありません。通常の 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 を使用しないシェルコマンドには Python は不要です。

ローカルサンドボックスエージェントの作成

この例では、ローカルリポジトリを repo/ 配下に配置し、ローカルスキルを遅延読み込みし、ランナーに実行用の Unix ローカルサンドボックスセッションを作成させます。エージェント定義がマニフェストと機能を保持し、実行設定では今回の実行で使用するサンドボックスクライアントだけを選択します。

UnixLocalSandboxClient は、macOS と Linux のどちらでも、コマンドをホストプロセスとして実行します。このクライアントは、OS レベルのファイルシステムやネットワークの分離を追加しません。この例は、信頼できるローカル開発、または外部で分離された環境内で使用してください。信頼できない入力の影響を受けるコマンドを含め、信頼できないコマンドを実行する場合は、適切に設定された 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: ファイルシステムの編集や画像の確認、シェル、スキル、メモリ、コンパクションなど、サンドボックスネイティブのツール
runAs: モデルに公開するツールで使用する、サンドボックス内のユーザー ID
sandbox.client: サンドボックスのバックエンド
sandbox.session、sandbox.sessionState、または sandbox.snapshot: 後続の実行で以前の作業に再接続する方法

次のステップ

コンセプト: マニフェスト、機能、権限、スナップショット、実行設定、組み合わせのパターンを理解します。
サンドボックスクライアント: Unix ローカル、Docker、ホスト型プロバイダー、マウント戦略を選択します。
エージェントメモリ: 過去のサンドボックス実行から得た知見を保存し、再利用します。

シェルアクセスがたまに使うツールの 1 つにすぎない場合は、ツールで紹介しているホスト型シェルから始めてください。ワークスペース管理、サンドボックスクライアントの選択、サンドボックスセッションの再開動作が設計の一部となる場合は、サンドボックスエージェントを利用してください。