コンテンツにスキップ

クイックスタート

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

SDK は、ファイルのステージング、ファイルシステムツール、シェルアクセス、サンドボックスのライフサイクル、スナップショット、プロバイダー固有の接続処理を自分で組み合わせなくても、この実行ハーネスを提供します。通常の Agent と Runner のフローはそのままに、ワークスペース用の Manifest、サンドボックスネイティブなツール向けの capabilities、そして作業の実行場所を指定する sandbox 実行オプションを追加します。

前提条件

Section titled “前提条件”
  • Node.js 22 以上
  • OpenAI Agents SDK の基本的な知識
  • サンドボックスクライアント。ローカル開発では、まず UnixLocalSandboxClient から始めてください

この quickstart は Node.js と npm コマンドを使いますが、SDK は Node.js に限定されません。プロジェクト側で互換性のあるパッケージ解決とランタイム API を使っていれば、Sandbox agent は Deno や Bun でも実行できます。

インストール

Section titled “インストール”

まだ SDK をインストールしていない場合:

Terminal window
npm install @openai/agents

Docker ベースのサンドボックスでは、ローカルに Docker をインストールし、@openai/agents/sandbox/local の DockerSandboxClient を使用してください。

tty: true を使った対話型のローカル PTY セッションを使用する場合、SDK を実行するプロセスでは python3 として、または OPENAI_AGENTS_PYTHON 経由で Python 3 を利用できる必要があります。非 PTY のシェルコマンドでは Python は不要です。

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

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

この例では、ローカルリポジトリを 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);

主な選択肢

Section titled “主な選択肢”

基本的な実行が動いたら、多くの人が次に検討する選択肢は次のとおりです。

  • defaultManifest: 新しいサンドボックスセッション向けのファイル、リポジトリ、ディレクトリ、マウント
  • instructions: プロンプトをまたいで適用される短いワークフロールール
  • baseInstructions: SDK のサンドボックスプロンプトを置き換えるための高度なエスケープハッチ
  • capabilities: ファイルシステム編集 / 画像検査、シェル、skills、メモリ、compaction などのサンドボックスネイティブなツール
  • runAs: モデル向けツールにおけるサンドボックスユーザー ID
  • sandbox.client: サンドボックスバックエンド
  • sandbox.session、sandbox.sessionState、または sandbox.snapshot: 後続の実行を以前の作業に再接続する方法

次のステップ

Section titled “次のステップ”

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