OpenAI Agents SDK ネイティブサンドボックスと Manifest ガイド

OpenAI は 2026 年 4 月 15 日に重要な Agents SDK アップデートをリリースしました。その手がかりはローンチ記事にあるインストール行、pip install "openai-agents>=0.14.0" でした（OpenAI）。このバージョン行には意味があります。これは新しいプロンプトテンプレートでも、また別の function calling ラッパーでもありません。OpenAI が、ファイル操作、シェル操作、パッチ適用、サンドボックスのライフサイクル、ワークスペース記述を SDK レベルのプリミティブへ移したということです。

コーディングエージェント、ドキュメントエージェント、データクリーンアップエージェント、リポジトリ保守ボットを構築する開発者にとって、この設計変更はシンプルです。Docker、一時ディレクトリ、ツールスキーマ、ファイルのステージング、リトライロジックの周りに、壊れやすい同じハーネスを各チームが作り直すのをやめる、ということです。SDK は今や、モデルネイティブなハーネス、サンドボックスネイティブな実行、ファイルシステムツール、MCP、AGENTS.md、シェルアクセス、apply_patch、そしてポータブルなワークスペースを記述するための Manifest 抽象化を提供します。

変化：ツール呼び出しから本物のワークスペースへ

元の Agents SDK は、エージェント、ツール、ハンドオフ、ガードレール、トレーシングといったオーケストレーションにすでに有用でした。4 月のアップデートでは、長時間にわたってファイルを扱う必要があるエージェントに欠けていたランタイムの形が追加されました。

OpenAI は、更新された SDK について、制御されたサンドボックス環境内でファイルを調査し、コマンドを実行し、コードを編集し、長期的なタスクに取り組めるエージェントを開発者が構築できるようにするものだと説明しています（OpenAI）。ここで鍵となるのは「制御されたワークスペース」という表現です。本格的なファイル操作エージェントに必要なのは、ツールのリストだけではありません。ルートディレクトリ、マウントされた入力、出力先、シェル、権限、スナップショット、そしてコンテナが落ちたときに再開する方法が必要です。

このアップデート以前の典型的な本番構成は、次のようなものでした。

• 一時ワークスペースを作成する
• そこへファイルをコピーする
• 読み取り、書き込み、シェル、パッチ用のツールを公開する
• パスを手動で検証する
• サンドボックスまたはコンテナを起動する
• 成果物を収集する
• ジョブが長時間実行される場合は状態をスナップショットする
• そのすべてをモデル向けの指示に変換する

多くのエージェントプロジェクトがひそかに複雑化するのは、このグルーコードの部分です。新しい SDK は、その多くを第一級の設定へ変えます。

OpenAI のローンチ記事では、サンドボックスプロバイダーとして Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel の組み込みサポートに加え、「bring your own sandbox」の経路も挙げられていました（OpenAI）。ローンチ時点で 7 つのホステッドプロバイダーに加え、ローカル開発の選択肢があるということです。

Manifest はポータビリティ層

Manifest 抽象化は、このリリースで最も実用的な部分です。モデルが作業を始める前に、サンドボックスのワークスペースに何を含めるべきかを記述します。

Python ドキュメントでは、Sandbox Agents はベータ版とされ、Python 3.10 以上を必要とし、モデルに永続的なワークスペースを与えて、ドキュメントセットの検索、ファイル編集、コマンド実行、成果物生成、保存済みサンドボックス状態からの再開を可能にする方法として紹介されています（OpenAI Agents SDK Python docs）。

コンパクトな Python の形は次のようになります。

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import LocalDir
from agents.sandbox.sandboxes.unix_local import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Repo maintainer",
    model="gpt-5.5",
    instructions="Read repo/task.md, edit with apply_patch, then run the targeted test.",
    default_manifest=Manifest(entries={"repo": LocalDir(src="./repo")}),
)

result = await Runner.run(
    agent,
    "Fix the failing test and summarize the change.",
    run_config=RunConfig(
        sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
    ),
)

重要なのは構文ではありません。契約です。Manifest は、ローカルファイル、ディレクトリ、Git リポジトリ、合成ファイル、環境変数、ユーザー、グループ、出力ディレクトリ、リモートストレージのマウントを記述できます。JavaScript ドキュメントでは、Manifest エントリのパスはワークスペース相対であり、絶対パスにはできず、.. によってワークスペース外へ抜けることもできないとされています。これはまさに、各プロンプトで覚えておくのではなく、ランタイムに強制してほしい退屈で重要な制約です（OpenAI Agents SDK JS docs）。

Capabilities：シェル、ファイルシステム、スキル、メモリ、コンパクション

SandboxAgent は、一時フォルダを持つだけの通常のエージェントではありません。サンドボックス固有の capabilities を備えています。

JS の概念ドキュメントでは、組み込み capabilities として shell()、filesystem()、skills()、memory()、compaction() が挙げられています（OpenAI Agents SDK JS docs）。ここではデフォルトが重要です。ドキュメントには、Capabilities.default() には filesystem、shell、compaction が含まれると記載されています。つまり、一般的なコーディングエージェントのループは、もはや個別実装のツール定義の山ではなくなるということです。

ファイルシステム capability は、パッチ形式のファイル編集を公開します。シェル capability は、サンドボックスセッション内でのコマンド実行を公開します。スキルにより、専門的な指示や手順を段階的に開示できます。メモリとコンパクションは、長時間の実行で有用な状態を保ちつつ、以前のトークンをすべて次のターンへ詰め込むことを避けるのに役立ちます。

これは、強力なコーディングエージェントが実際に動作する方法と一致しています。調査する。コマンドを実行する。ファイルを編集する。より小さなコマンドを実行する。差分を確認する。何が変わったかを要約する。ハーネスが各ステップを無関係な API 呼び出しとして扱うと、モデルは自分の世界を再構築することに注意を使いすぎます。サンドボックスセッションは、モデルに立つ場所を与えます。

AGENTS.md もこのモデルに自然に合います。オープンな AGENTS.md サイトは、これをコーディングエージェントを導くための Markdown 形式だと説明し、60,000 を超えるオープンソースプロジェクトで使われていると述べています（AGENTS.md）。このファイルには、ビルドコマンド、テスト手順、スタイルルール、リポジトリ固有の注意点を含めるべきです。サンドボックスの世界では、AGENTS.md は各タスクに巨大なプロンプトとして貼り付けるものではなく、ワークスペースローカルの運用コンテキストになります。

Python ファースト、TypeScript が追随

ローンチ時点では、これは Python ファーストでした。TechCrunch は 4 月 15 日、新しいハーネスとサンドボックス機能はまず Python で提供され、TypeScript サポートは後日予定されていると報じました（TechCrunch）。PyPI も日付を裏付けています。openai-agents のバージョン 0.14.0 と 0.14.1 は 2026 年 4 月 15 日にアップロードされました（PyPI）。

2026 年 6 月 16 日時点では、実務上の状況はよりバランスが取れています。公式 JS ドキュメントには現在、ベータ版の Sandbox Agents が含まれ、Node.js 22 以上が必要とされ、Manifest、SandboxAgent、UnixLocalSandboxClient、Docker サポート、そして @openai/agents-extensions 経由のホステッドプロバイダークライアントが示されています（OpenAI Agents SDK JS quickstart）。JS ドキュメントでは、パッケージ解決とランタイム API に互換性がある場合、Deno と Bun でも動作可能だとも記されています。

領域	Python	TypeScript / JavaScript
4 月 15 日時点のローンチ状況	最初にサポートされた経路	後日予定
現在のサンドボックスドキュメント	ベータ、Python 3.10+	ベータ、Node.js 22+
ローカルサンドボックス	UnixLocalSandboxClient	UnixLocalSandboxClient
Docker サンドボックス	openai-agents[docker]	DockerSandboxClient
ホステッドプロバイダー	SDK 統合経由でサポート	@openai/agents-extensions のプロバイダー経路

だからといって、2 つのエコシステムが同一という意味ではありません。Python は元々のローンチ面であり、多くの例はいまだにまずそちらに出てきます。TypeScript には現在、本物のサンドボックスエージェントをプロトタイプするのに十分な公式の表面積がありますが、ホステッドプロバイダーの詳細、PTY の挙動、マウント、ライフサイクルサポートについては、バックエンドごとに慎重に読む必要があります。

今ならファイル操作エージェントをどう構成するか

誤りは、サンドボックスを魔法の安全箱として扱うことです。これはランタイム境界であり、プロダクト仕様ではありません。ワークスペースは依然として設計する必要があります。

クリーンな構成は次のようになります。

• repo/：作業ツリーまたはマウントされたリポジトリ
• task.md：モデルが最初に読むべきタスク仕様
• inputs/：読み取り専用のドキュメント、データセット、スクリーンショット、ログ
• output/：最終的に生成された成果物を置く唯一の場所
• AGENTS.md：ビルド、テスト、スタイル、安全性に関する指示
• サンドボックスユーザー：バックエンドが対応している場合は非 root の ID
• Manifest env：デフォルトで永続化される非シークレット設定、シークレットはエフェメラルとしてマーク

Manifest は入力を記述すべきです。エージェントの instructions はワークフローを記述すべきです。ユーザープロンプトは一回限りのタスクを記述すべきです。これらは分離しておきましょう。JS ドキュメントでは、Manifest に属する長い参考資料を instructions に詰め込まないよう明示的に警告しています（OpenAI Agents SDK JS docs）。

本番では、デモの経路ではなく、影響範囲に基づいてバックエンドを選びます。Unix-local は開発には問題ありません。再現性が必要な場合は Docker の方がよいデフォルトです。実行ごとのクリーンな分離、リモート実行、スケーリング、プロバイダー固有のスナップショット挙動が必要な場合は、ホステッドプロバイダーが適しています。JS クライアントのドキュメントでは、ホステッドプロバイダーのサポートはさまざまであり、開発者は環境変数、ポート、PTY、スナップショット、クリーンアップ挙動についてプロバイダーのドキュメントを確認すべきだと述べています（OpenAI Agents SDK JS clients）。

エコシステムとしての読み解き

このアップデートが重要なのは、ファイル操作エージェントの形を標準化するからです。業界はすでにいくつかのプリミティブに収束していました。外部ツール向けの MCP、リポジトリ指示向けの AGENTS.md、実際の調査のためのシェル、レビュー可能な編集のためのパッチ適用、封じ込めのためのサンドボックスです。OpenAI の Agents SDK は今や、それらの部品を、開発者が実際に組み合わせられるランタイムとしてパッケージ化しています。

鋭いエッジとして残るのは権限です。広いネットワークアクセス、書き込み可能なマウント、長期有効な認証情報、曖昧な指示を持つサンドボックス化されたエージェントは、それでも被害を生み得ます。Manifest は、ワークスペースの入力と付与が可視化されるため役立ちます。しかし、承認ポリシー、シークレット衛生、依存関係の固定、成果物レビューの必要性をなくすものではありません。

今日の最良のユースケースは、「エージェントがすべてをこなす」ことではありません。より狭く、より価値のあるものです。モデルに、境界づけられたワークスペース、明確なタスクファイル、リポジトリローカルの指示、シェルとパッチツール、そして 1 つの明示的な検証経路を与えることです。使い捨て環境のジュニアエンジニアのように作業させましょう。そして差分を確認します。

これは、チャットループの周りにまた別の中途半端なサンドボックスを手作りするより、はるかに健全な抽象化です。

これらのモデルを実際に試したい読者は、base_url を 1 つ変更するだけで、OpenAI 互換 API を使って onehop 経由で呼び出せます。ファーストパーティより安価で、新規アカウントにはカード不要で $10 の無料クレジットが付与されます：onehop で Claude などのモデルを呼び出す、または $10 の無料クレジットにサインアップ。