クイックスタート

エージェントは、ファイルシステム上の実ファイルを操作できると、最も効果的に機能します。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 を実行するプロセスでは、Python 3 を python3 として、または OPENAI_AGENTS_PYTHON 経由で利用できる必要もあります。非 PTY の shell コマンドでは Python は必要ありません。

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

この例では、ローカルリポジトリを repo/ 配下にステージングし、ローカルスキルを遅延読み込みして、実行用の Unix ローカルサンドボックスセッションを Runner が作成できるようにします。エージェント定義がマニフェストとケイパビリティを保持し、実行設定では今回の実行に使用するサンドボックスクライアントのみを選択します。

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: モデルが使用するツール向けのサンドボックスユーザー ID
sandbox.client: サンドボックスのバックエンド
sandbox.session、sandbox.sessionState、または sandbox.snapshot: 後続の実行で以前の作業に再接続する方法

次のステップ

コンセプト: マニフェスト、ケイパビリティ、権限、スナップショット、実行設定、構成パターンの理解
サンドボックスクライアント: Unix ローカル、Docker、ホステッドプロバイダー、マウント戦略の選択
エージェントメモリ: 以前のサンドボックス実行から得た知見の保存と再利用

shell アクセスが必要になるのが一時的なツール利用に限られる場合は、ツールの組み込み shell から始めてください。ワークスペースの分離、サンドボックスクライアントの選択、サンドボックスセッションの再開動作が設計の一部となる場合は、サンドボックスエージェントを使用してください。