OpenAI Agents SDK 新ハーネスとは？sandbox・subagents・code modeの使い方を徹底解説

OpenAI Agents SDKの「新ハーネス」は、エージェントの司令塔となる制御層と、コードやファイル操作を実行するサンドボックス層を正式に分離した最新アーキテクチャです。 2026年4月15日のアップデートでPython版（openai-agents v0.14.x）に一般提供が開始され、Manifestによるワークスペース定義・AGENTS.mdによる指示・複数クラウドサンドボックスとの連携が公式プリミティブとして組み込まれました。

本記事では、公式ドキュメントとOpenAIの発表内容をもとに、新ハーネスの全体像・sandbox構成・subagentsとcode modeの現状・最小動作コード・対応プロバイダ比較・セキュリティ運用までを、1ページで判断できるようにまとめています。

この記事でわかること

• 新ハーネスが「従来のAgents SDK」とどこが違うのか
• 「ハーネス」と「サンドボックス」の役割分担
• pip install openai-agentsから最初のエージェントを動かすまでの手順
• Manifestの書き方と対応サンドボックスプロバイダ（Cloudflare / Modal / Vercel / E2B など）の違い
• subagentsとcode modeの現在の提供状況と、正式リリース前に使える代替パターン
• 料金（OpenAI API料金＋sandboxプロバイダ料金）の考え方
• セキュリティ・承認フロー・スナップショット運用の注意点
• Claude Agent SDK・LangGraph・CrewAIとの使い分け
• 向いているチーム／向いていないチーム
• よくある質問と次の学習ステップ

誰向けの記事か

• OpenAI Agents SDKで本格的なエージェントを構築しようとしているエンジニア・PdM
• 既存のhandoffs中心の実装を新ハーネスへ移行するか迷っているチーム
• Claude Agent SDK / LangGraph / CrewAI と比較して選定したいテックリード
• サンドボックス実行環境を本番運用レベルで設計したいSRE・プラットフォームチーム

OpenAI Agents SDK 新ハーネスとは

OpenAI Agents SDKは、OpenAIが公開しているエージェント開発用の軽量Pythonフレームワークで、Agent / Handoff / Guardrail / Sessionといった少数の抽象化だけでマルチエージェントワークフローを構築できます。リポジトリはopenai-agents-pythonで公開されており、MITライセンスのOSSです。

2026年4月15日公開の「次世代Agents SDK」では、従来のオーケストレーション層に加えて、モデルネイティブなハーネス（制御層）とネイティブサンドボックス実行層（計算層）が公式プリミティブとして追加されました。これにより、長時間タスク・ファイル操作・シェル実行を含む本格的なエージェントを、セキュリティ境界をはっきり引いた形で実装できます。

一言でいうとどんな役割か

• ハーネス＝エージェントの司令塔。計画・メモリ・コンテキスト圧縮・ツール呼び出し制御を担う。
• サンドボックス＝エージェントの作業部屋。ファイル操作・シェル実行・パッケージインストール・外部ストレージ接続など「実処理」を隔離された環境で行う。
• 両者を明確に分けたことで、モデルが暴走しても認証情報や上位制御プレーンにアクセスできない設計になっている。

従来版（〜v0.13系）は「handoffs」「agents-as-tools」といった抽象化が中心で、サンドボックス部分は開発者が個別に組む必要がありました。新ハーネスはこの「組み方の空白」を公式が埋めた、と捉えるとわかりやすいです。

2026年4月アップデートで何が変わったか

新ハーネス導入で追加・変更された主要ポイントを整理します。

出典: OpenAI公式ブログ「The next evolution of the Agents SDK」およびGitHub Releases

ハーネスとサンドボックスの役割分担

新ハーネスを最速で理解する鍵は、「司令塔」と「作業部屋」のメタファーです。

ハーネス（制御層）が担当すること

• エージェントのプランニングと状態管理（どのツールをいつ呼ぶか）
• メモリとセッションの永続化（Redis / MongoDB など複数バックエンド）
• AGENTS.mdの読み込み・Skillsの動的ロード
• Responses APIのサーバサイドCompactionによるコンテキスト圧縮
• スナップショット・再開のオーケストレーション
• 承認ハンドラ（apply_patch等の危険操作は人間確認を挟める）

サンドボックス（計算層）が担当すること

• ファイル操作（Filesystem capability）
• シェル実行（Shell capability）
• パッケージインストール・ビルド
• 外部ストレージマウント（S3 / GCS / Azure Blob / R2）
• GPU利用やロングランニングタスクの実行
• 生成した成果物のスナップショット保存

認証情報やAPIキーはサンドボックス側にプロバイダネイティブな仕組み（Cloudflare Secrets、Modal Secretsなど）で渡し、モデルが直接値を扱わない設計になっています。プロンプトインジェクションが発生しても、制御プレーンから秘密情報が漏れないようにするためです。

新ハーネスの主な機能

1. Manifestでワークスペースを宣言する

Manifestは「このエージェントはどこのファイル・どのリポジトリ・どの外部ストレージを使うか」をコードとして記述する設計図です。ローカルディレクトリ、Gitリポジトリ、S3バケットなどを1つの定義にまとめられます。

from agents.sandbox import Manifest
from agents.sandbox.manifest import LocalDir, GitRepo

manifest = Manifest(
    entries=[
        LocalDir(path="./workspace", mount_as="/workspace"),
        GitRepo(
            url="https://github.com/openai/openai-cookbook.git",
            mount_as="/cookbook",
            ref="main",
        ),
    ]
)

2. 標準で搭載されるツール

• shell ツール — コマンド実行。タイムアウト、作業ディレクトリ、環境変数を指定可能。
• apply_patch ツール — unified diff形式でファイルを編集。承認ハンドラ（bool / 関数）を挟める。
• Filesystem capability — ファイル読み書き・列挙・検索。
• Compaction capability — コンテキスト圧縮を自動管理。

3. AGENTS.mdとSkills

• AGENTS.md — リポジトリ直下に置くと、ハーネスが自動で読み込みエージェントの行動ガイドラインにする。Markdown形式でルール・禁止事項・好みの書き方を記述できる。
• Skills — SKILL.mdマニフェストを含むバージョン管理された"プレイブック"。必要なときだけ動的にロードし、システムプロンプトの肥大化を防ぐ。例：Excel生成、PDF出力、Viteアプリのデバッグ手順など。

4. Memory capability

• Memoryを有効にすると、前回のRunで学んだ内容をMEMORY.mdやmemory_summary.mdに蒸留し、次回のRunに引き継げる。
• 単なる会話履歴（Session）より長期タスクに向いたメタ知識の保持に適しています。

5. サーバサイドCompaction

• 長時間稼働で膨らむコンテキストをResponses API側で自動圧縮する仕組み。開発者が自力でトークン管理コードを書かなくても、ハーネスが一定ポリシーで圧縮を挟みます。

ネイティブサンドボックス実行環境

Agents SDK v0.14系では、9種類のSandboxClientが同梱されています（2026年4月時点）。

外部ストレージはAWS S3 / Google Cloud Storage / Azure Blob Storage / Cloudflare R2をManifestからマウントできます。スナップショットはsession_state・RunStateを通じて保存でき、障害からの再開が可能です。

各プロバイダの最大実行時間・同時実行数・メモリ上限はプロバイダごとに異なるため、本番運用前に各社のドキュメントを必ず確認してください。

インストールと最小動作サンプル

前提

• Python 3.10以上
• WindowsではUnixLocalSandboxClientを使うためにWSL等のUnix環境が必要
• OpenAI APIキー（OPENAI_API_KEY環境変数）

インストール

# pipの場合
pip install openai-agents

# uvの場合
uv add openai-agents

最小動作コード（ローカルUnixサンドボックス）

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


async def main():
    manifest = Manifest(
        entries=[LocalDir(path="./workspace", mount_as="/workspace")]
    )

    agent = SandboxAgent(
        name="ReviewAgent",
        instructions=(
            "You are a code review agent. "
            "Inspect the /workspace directory and summarize README.md."
        ),
        default_manifest=manifest,
    )

    result = await Runner.run(
        agent,
        "Inspect the repo and summarize it in 3 bullets.",
        run_config=RunConfig(
            sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())
        ),
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

• SandboxAgentは従来のAgentと似たAPIですが、default_manifestを受け取れる点が異なります。
• RunConfig(sandbox=SandboxRunConfig(client=...))でサンドボックスクライアントを差し替えると、そのままクラウドサンドボックスへ移行できます。

Cloudflare Sandboxで動かす場合

Cloudflare WorkersでSandbox APIをHTTP公開し、Pythonエージェントから操作するパターンが公式チュートリアルで案内されています（所要約20分）。

from agents.sandbox.sandboxes.cloudflare import CloudflareSandboxClient

client = CloudflareSandboxClient(
    endpoint="https://your-sandbox.example.workers.dev",
    api_token="...",
)

詳細はCloudflare Sandbox公式チュートリアルを参照してください。

Manifestの書き方（本番運用を意識）

Manifestは「どこから入力を読み、どこに成果物を書くか」を宣言するコードです。本番運用では次のような構成になります。

from agents.sandbox import Manifest
from agents.sandbox.manifest import (
    LocalDir,
    GitRepo,
    S3Mount,
)

manifest = Manifest(
    entries=[
        # 自社リポジトリ
        GitRepo(
            url="https://github.com/your-org/your-repo.git",
            mount_as="/repo",
            ref="feature/ai-agent",
        ),
        # 入力データ
        S3Mount(
            bucket="your-inputs",
            prefix="reports/2026-04/",
            mount_as="/inputs",
            mode="read",
        ),
        # 出力用
        S3Mount(
            bucket="your-outputs",
            prefix="agent-runs/",
            mount_as="/outputs",
            mode="write",
        ),
    ]
)

• 認証情報はエージェントに直接渡さない。プロバイダ側のシークレット機構（Cloudflare Secrets / Modal Secrets など）とdomain_secretsを組み合わせて、ランタイムに解決させます。
• 読み取り専用マウントを活用する。出力先だけ書き込み可能にすれば、想定外のデータ破壊を防げます。

Subagents（サブエージェント）の現状と代替パターン

現状：公式プリミティブは「近日提供予定」

OpenAIは「今後数ヶ月以内にPython・TypeScript両SDKにsubagentsを展開予定」と公表していますが、2026年4月時点では正式プリミティブとして一般提供されていません。クラス名・メソッド名の最終仕様も未公開です。

既存機能で組める代替パターン

現時点でも、Agents SDKには以下の機能があり、実質的にサブエージェント構造は組めます。

1. handoffs — 親エージェントが別エージェントに処理を引き渡す。
2. agents as tools — 別エージェントを「ツール」として親エージェントから呼び出せる。
3. async subagent pool + orchestrator（Modalブログの実装例） — 並列実行サブエージェントプールを自前で構築し、オーケストレータから分散投入する。

最小限の「orchestrator + 並列subagent」疑似コードを示します。

import asyncio
from agents import Agent, Runner

researcher = Agent(
    name="Researcher",
    instructions="Gather facts on a specific topic.",
)

writer = Agent(
    name="Writer",
    instructions="Compose a concise summary from facts.",
)

async def orchestrate(topic: str):
    # 並列でサブエージェントを走らせる
    research_task = asyncio.create_task(
        Runner.run(researcher, f"Research: {topic}")
    )
    # 収集結果を待ってライターに渡す
    research = await research_task
    summary = await Runner.run(
        writer,
        f"Summarize in 3 bullets:\n{research.final_output}",
    )
    return summary.final_output


print(asyncio.run(orchestrate("Cloudflare Sandboxのメリット")))

公式プリミティブが出るまでは、既存のagents-as-tools＋asyncio並列Runnerで十分な実用性があります。正式プリミティブが出た際は、この抽象化を置き換える形でマイグレーションできます。

Code Mode（コードモード）の現状と代替パターン

現状：こちらも「近日提供予定」

Code Modeは「エージェントがコードを生成して実行することでタスクを進める」専用モードで、OpenAI Codex的な自律開発体験を意図しています。ただし正式APIシグネチャは2026年4月時点で未公開です。名称自体も変更される可能性があります。

既存ツールで実現できる範囲

既存のshellツールとapply_patchツールの組み合わせで、実質的にはCode Modeに近い体験を構築できます。OpenAI Cookbookの「Build a coding agent with GPT 5.1」には、次のような流れのサンプルが掲載されています。

1. ユーザーから要件を受け取る
2. エージェントがリポジトリをshellで探索し、関連ファイルを読む
3. apply_patchで差分を提案する（承認ハンドラでレビュー）
4. テストコマンドをshellで実行
5. 失敗したら再度パッチを書く

from agents import Agent
from agents.tools.shell import shell_tool
from agents.tools.apply_patch import apply_patch_tool

coding_agent = Agent(
    name="CodingAgent",
    instructions=(
        "You are a senior engineer. "
        "Explore the repo, propose a patch, and run tests."
    ),
    tools=[
        shell_tool(timeout_seconds=120),
        apply_patch_tool(require_approval=True),
    ],
)

• require_approval=Trueにすることで、patch適用前に必ず承認を要求できます。
• 関数として(run_context, operation, call_id) -> boolを渡せば、条件付き自動承認も可能です。

料金の考え方

新ハーネスを使う場合のコストは、OpenAI API料金とサンドボックスプロバイダ料金の二段構造で考えるのがわかりやすいです。

代表的なサンドボックスプロバイダの料金体系（概要）

具体的な円建て料金は為替・プロバイダ側の改定で変動します。 正確な金額は必ずOpenAI公式価格ページと各プロバイダの公式ページで確認してください。

セキュリティ・運用上の注意点

企業導入で押さえておきたい「安全運用チェックリスト」を整理します。

• ハーネスと計算層を分離する設計を守る — 認証情報はサンドボックス側のシークレット機構に置く。モデルが生成するテキストにAPIキーを直接渡さない。
• domain_secretsでネットワーク境界を絞る — 組織レベルの許可ドメインを最小化し、認証付きリクエストはリクエスト単位で許可する。
• apply_patchに承認ハンドラを設定する — バックエンドの自動書き換えを暴走させない。
• AGENTS.mdで禁則事項を明記する — 「本番DBに直接触らない」「秘匿ファイルパスを開示しない」など明文化。
• スナップショットから再開できる設計にする — 長時間タスクの進捗を保護し、障害後のリトライを安全に。
• 成果物は人間レビューを必須に — 公式ガイドもサンドボックスが生成した成果物の人間レビューを必須と明記しています。
• コンプライアンス要件は個別確認 — SOC2 / ISO27001等の認証が新ハーネス機能にどこまで適用されるかは契約・利用規約側の個別確認が必要です。

他のエージェントフレームワークとの比較

実装判断で「他SDKと比べてどうか」を整理する際は、以下の比較表が参考になります。

参考: Langfuse AI Agent Framework比較（2025-03-19）、LangChain公式比較ページ

関連記事:

• AIエージェントフレームワーク比較記事はこちら
• Claude Agent SDK／Managed Agentsとの違いはこちら
• LangGraph・CrewAIとの選び分けはこちら

向いているチーム／向いていないチーム

こんなチームにおすすめ

• すでにOpenAIのAPIを本番で使っていて、モデル・請求体系を揃えたい
• Python中心の開発チームで、エージェントを新しく作る／リアーキテクトしたい
• サンドボックス実行（ファイル・シェル・パッケージインストール）が必要なタスクを扱う
• 長時間タスクをスナップショット復旧付きで回したい
• Cloudflare / Modal / Vercel など、既存クラウドの上にエージェント実行環境を載せたい
• マルチエージェント構成を公式抽象化に近い形で組みたい

今は見送った方がよいケース

• TypeScriptで新ハーネスを使いたいチーム（2026年4月時点では従来機能中心）
• モデルをAnthropic（Claude）やGoogle（Gemini）中心で組みたい場合 — 他SDKの方が自然
• 自社で厳密にハーネス挙動を制御したい研究開発用途 — LangGraphのグラフDSLが向く場合あり
• Code Mode / Subagentsの正式プリミティブが必須の要件がある（現状は未提供のため代替実装が必要）
• 企業コンプライアンス要件で、認証範囲が契約上明確になっていないと導入できないケース

よくある質問

Q1. 新ハーネスは既存のhandoffs実装を壊しますか？

新ハーネスは従来抽象化（Agent / Handoff / Guardrail / Session）を上書きではなく拡張する形で追加されています。従来コードは引き続き動作します。ただし、一般的にはMinor/Majorリリースのたびに細かな仕様調整は入りやすいため、本番運用前にGitHub Releasesで差分を確認するのが無難です。

Q2. TypeScript版で新ハーネスはいつ使えますか？

OpenAIは「Python/TypeScript両SDKへ展開予定」と公表していますが、2026年4月時点でTypeScript版の正式対応時期は未公表です。TS中心のチームは、当面は従来機能を使いつつ、Python側で先行検証する構成が現実的です。

Q3. Code ModeとSubagentsはいつ使えますか？

どちらも「近日提供予定」とされており、2026年4月時点で一般提供はされていません。現時点ではshell + apply_patchツール、handoffs、agents-as-tools、asyncio並列Runnerで代替実装するのが実務解です。

Q4. どのサンドボックスプロバイダから選ぶべきですか？

以下のような切り分けが目安です。

• まずは動かしたい: UnixLocalSandboxClient（ローカル）
• CI/社内インフラで回したい: DockerSandboxClient
• エッジで低レイテンシに動かしたい: Cloudflare Sandbox
• GPUで回したい・サーバレスで立ち上げたい: Modal
• Vercel上のアプリに組み込みたい: Vercel Sandbox

Q5. 料金はいくらかかりますか？

SDK自体は無料ですが、OpenAI API料金とサンドボックスプロバイダ料金が発生します。金額は使うモデル・トークン数・サンドボックス実行時間で変動するため、まずは小さなタスクで実測してから本番計算するのが安全です。

Q6. Claude Agent SDKやLangGraphから移行する価値はありますか？

「OpenAIモデルを中心に据え、Python／サンドボックス実行が必要」であれば、新ハーネスは導入価値が高い選択肢です。逆にClaudeモデル前提や、既存のLangGraphグラフ資産が大きいチームは、無理に全面移行せず役割分担する判断もあり得ます。

Q7. 長時間タスクは安全に動かせますか？

スナップショット（session_state / RunState）とCompactionによって、長時間タスクの進捗を保護しやすい設計です。ただし、各サンドボックスプロバイダの実行時間上限は別途あるため、本番導入前に必ず確認してください。

Q8. セキュリティ監査はどこを重点的にチェックすべきですか？

（1）認証情報の受け渡し経路（domain_secretsとプロバイダシークレット機構の組み合わせ）、（2）apply_patch承認フロー、（3）ネットワーク許可ドメイン、（4）AGENTS.mdでの禁則記述、（5）スナップショット・監査ログの保管方針、の5点が定番です。

まとめ

• OpenAI Agents SDK 新ハーネスは、制御層と計算層を公式に分離した2026年4月の大型アップデートで、Pythonを中心に本格エージェント開発が一気にやりやすくなりました。
• Manifest + SandboxClientでワークスペースと実行環境を宣言的に記述でき、Cloudflare / Modal / Vercel / E2Bなど9プロバイダに公式対応しています。
• Subagents・Code Modeは「近日提供予定」段階。既存のhandoffs / agents-as-tools / shell / apply_patchで代替実装が可能です。
• 本番導入では認証情報の取り扱い・承認ハンドラ・スナップショット運用を最初に設計に組み込むのが安全です。

次の一歩として、エージェントフレームワーク全体像やClaude系／LangGraph系と比較したい場合は、以下の関連記事も参考にしてください。

• AIエージェントフレームワーク おすすめ 比較
• Claude Managed Agents とは
• AIエージェントとは
• エージェンティックエンジニアリングとは
• AIエージェント セキュリティ 対策

公式一次情報（随時更新）

• OpenAI公式ブログ「The next evolution of the Agents SDK」
• 公式ドキュメント（日本語）
• Sandbox Agentsガイド
• GitHubリポジトリ
• GitHub Releases