クイックスタート

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

SDK は、ファイルのステージング、ファイルシステムツール、シェルアクセス、サンドボックスのライフサイクル、スナップショット、プロバイダー固有の連携コードを自分でつなぎ合わせなくても、その実行ハーネスを利用できるようにします。通常の Agent と Runner の流れはそのままに、ワークスペース用の Manifest、サンドボックスネイティブなツール用の capabilities、作業の実行場所を指定する 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 を実行するプロセスでは python3、または OPENAI_AGENTS_PYTHON 経由で利用できる Python 3 も必要です。非 PTY のシェルコマンドでは Python は不要です。

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

この例では、repo/ 配下のローカルリポジトリをステージングし、ローカルスキルを遅延読み込みし、ランナーがその実行用に Unix ローカルのサンドボックスセッションを作成できるようにします。エージェント定義がマニフェストと 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({
        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: 後続の実行で以前の作業へ再接続する方法

次のステップ

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

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