OpenAI Agents SDK 新ハーネスとは？sandbox・subagents・code modeの使い方【2026年最新版】

OpenAI Agents SDKの「新ハーネス」は、エージェントの制御層（司令塔）とサンドボックス実行層（作業部屋）を公式に分離した、2026年4月の大型アップデートです。 最新版はv0.17.5（2026年6月11日リリース）で、サンドボックス機能はv0.14.0からベータ提供中、サブエージェント機能はPython版ベータで利用可能です。コードモードのみ現時点で未リリースです。

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

この記事でわかること

• 新ハーネスが「従来のAgents SDK（〜v0.13）」とどこが違うのか
• 「ハーネス（制御層）」と「サンドボックス（計算層）」の役割分担
• pip install openai-agents から最初のエージェントを動かすまでの手順
• Manifestの書き方と対応サンドボックスプロバイダー9種類の比較
• サブエージェント（ベータ・Python版）とコードモード（未リリース）の現在状況
• v0.16.0でデフォルトモデルがgpt-5.4-miniに変わった料金への影響
• CVE-2025-6514を含む最新セキュリティ情報
• Claude Agent SDK・LangGraph・CrewAIとの使い分け基準

誰向けの記事か

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

OpenAI Agents SDK 新ハーネスとは

OpenAI Agents SDKは、OpenAIが2025年3月11日に公開したエージェント開発用の軽量PythonフレームワークでMITライセンスのOSSです。前身の実験的ツール「Swarm」の本番対応アップグレード版として位置づけられており、Agent / Handoff / Guardrail / Sessionといった少数の抽象化だけでマルチエージェントワークフローを構築できます。GitHubリポジトリ（openai-agents-python）は2026年6月時点でスター27.2k、フォーク4.2kに達しています。

2026年4月15日公開の「The next evolution of the Agents SDK」では、従来のオーケストレーション層に加えて、モデルネイティブなハーネス（制御層）とネイティブサンドボックス実行層（計算層）が公式プリミティブとして追加されました。

出典: GitHub - openai/openai-agents-python

ハーネス・サンドボックスを一言で

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

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

バージョン別アップデート一覧（v0.14〜v0.17.5）

新ハーネスはv0.14.0で導入され、以降も継続的に改善されています。

出典: GitHub Releases

旧設計 vs 新ハーネス：何が変わったか

旧版（〜v0.13）と新ハーネス（v0.14以降）の主な変更点を整理します。

出典: OpenAI公式ブログ・GitHub Releases

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

新ハーネスを最速で理解する鍵は、制御層と計算層の分離です。

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

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

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

• ファイル操作（Filesystem capability）
• シェル実行（Shell capability）
• パッケージインストール・ビルド
• 外部ストレージマウント（S3 / GCS / Azure Blob / Cloudflare 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. 標準で搭載されるツール

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側で自動圧縮する仕組みです。開発者が自力でトークン管理コードを書かなくても、ハーネスが一定ポリシーで圧縮を挟みます。

ネイティブサンドボックス実行環境：9プロバイダー比較

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

出典: Vercel公式ドキュメント - Vercel Sandbox

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

プロバイダー選択の目安:

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

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

前提

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

インストール

# pip（最小）
pip install openai-agents

# Dockerサンドボックス対応
pip install "openai-agents[docker]"

# Vercelサンドボックス対応
pip install "openai-agents[vercel]" python-dotenv

# uv推奨（2026年現在）
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=...))でサンドボックスクライアントを差し替えると、そのままクラウドサンドボックスへ移行できます

Vercel Sandboxで動かす場合

from agents.sandbox.sandboxes.vercel import VercelSandboxClient

client = VercelSandboxClient(
    token="YOUR_VERCEL_TOKEN",
    team_id="YOUR_TEAM_ID",
    project_id="YOUR_PROJECT_ID",
)

.env.localにOPENAI_API_KEY、VERCEL_TOKEN、VERCEL_TEAM_ID、VERCEL_PROJECT_IDが必要です。デフォルトのタイムアウトは270秒です。詳細はVercel公式ガイドを参照してください。

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-06/",
            mount_as="/inputs",
            mode="read",
        ),
        # 出力用
        S3Mount(
            bucket="your-outputs",
            prefix="agent-runs/",
            mount_as="/outputs",
            mode="write",
        ),
    ]
)

認証情報はエージェントに直接渡さない。プロバイダー側のシークレット機構（Cloudflare Secrets / Modal Secretsなど）とdomain_secretsを組み合わせて、ランタイムに解決させます。

サブエージェント（Subagents）の現状【ベータ・Python版】

現在の提供状況（2026年6月18日時点）

サブエージェントはPython版ベータとして2026年4月15日に発表・提供開始されています。 TypeScript版への対応は後日予定とのみ記載があります。APIや仕様はベータのため変更される可能性があります。

Handoffとの違い

サブエージェントの主なユースケース例:

顧客対応エージェント（親）
├── 見積作成エージェント（子）
├── 在庫確認エージェント（子）
└── 配送追跡エージェント（子）

現行機能での代替パターン

ベータ仕様が安定するまで、既存機能で実質的にサブエージェント構造を組めます。

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("Vercel Sandboxのメリット")))

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

Code Mode（コードモード）の現状

現状：未リリース（2026年6月18日時点）

コードモードは「エージェントがPythonまたはTypeScriptのコードをワークフローの一部として実行できるファーストクラス機能」として発表済みです。Codexスタイルの自律的開発者体験を意図しています。ただし公式APIシグネチャは2026年6月時点で未公開です。想定ユースケースは次のとおりです。

• データ分析・グラフ・レポート生成
• ファイル変換・自動テスト実行
• 自然言語によるコード生成・実行

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

現時点ではshellツールとapply_patchツールの組み合わせで、Code Modeに近い体験を構築できます。

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適用前に必ず承認を要求できます。

料金の考え方

新ハーネスのコストはOpenAI API料金とサンドボックスプロバイダー料金の二段構造です。

SDK本体

無料（OSSのMITライセンス）。PyPI経由で自由に導入可能です。

v0.16.0からのデフォルトモデル変更の影響

v0.16.0でデフォルトモデルがgpt-4.1からgpt-5.4-miniに変更されました。旧デフォルト（gpt-4.1）と比較してコスト面では優位ですが、使用モデルが変わることでレスポンスの特性が変わる場合があります。移行時はテストを行ってから本番適用してください。

OpenAI APIモデル別料金（2026年6月確認）

出典: OpenAI公式APIプライシング

コスト最適化パターン（公式推奨）

• ガードレール処理 → gpt-4.1-mini（低コスト）
• 最終回答・高品質推論 → gpt-5.5
• バッチAPI（非同期24時間以内）→ 標準料金の50%
• モデル使い分けで50%前後のコスト削減が可能

サンドボックスプロバイダーの料金目安

具体的な金額は為替・プロバイダー側の改定で変動するため、必ず各社公式ページで確認してください。

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

制御プレーンと実行プレーンの分離がもたらすセキュリティ改善

新ハーネスの最大のセキュリティ上の特徴は「制御プレーン（APIキー等）と実行プレーン（コード実行）の分離」です。この設計により：

• プロンプトインジェクション攻撃が成功しても横展開（ラテラルムーブメント）が困難になる
• 本番インフラへの無断アクセスを防止
• システム整合性の保護が向上

最新のセキュリティ情報（2026年6月時点）

CVE-2025-6514（CVSS 9.6） — MCPプロキシライブラリmcp-remoteに深刻な脆弱性が報告されています。MCPサーバーとの統合を使用している場合は依存パッケージのバージョンを確認してください。詳しくはAIエージェントのセキュリティ対策ガイドを参照してください。

OpenAI自身は「プロンプトインジェクションはWebのスキャムと同様、完全には解決できない長期課題」と公言しており、ハーネスと実行プレーンの分離は軽減策の一つとして機能しますが、完全な防御にはなりません。

企業導入時の安全運用チェックリスト

• 認証情報はサンドボックス側のシークレット機構に置く。モデルが生成するテキストにAPIキーを直接渡さない
• domain_secretsでネットワーク境界を最小化する
• apply_patchに承認ハンドラを設定し、バックエンドの自動書き換えを防ぐ
• AGENTS.mdで禁則事項を明記する（「本番DBに直接触らない」「秘匿ファイルパスを開示しない」など）
• スナップショットから再開できる設計にして、長時間タスクの進捗を保護する
• 成果物は人間レビューを必須に（公式ガイドも明記）
• SOC2 / ISO27001等の認証範囲はOpenAIとの契約・利用規約を個別確認する

出典: Modal公式サイト

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

Claude Agent SDKとOpenAI Agents SDKの詳細比較はClaude Managed Agentsとはも参照してください。

どのフレームワークを選ぶべきか

• OpenAIモデルを中心に据えて、Python・サンドボックス実行が必要 → OpenAI Agents SDK
• Claudeモデルを使いたい・Anthropicエコシステムで統一したい → Claude Agent SDK
• フローを細かく制御したい・既存のLangChainエコシステムがある → LangGraph
• シンプルなマルチエージェント構成を素早く作りたい → CrewAI

こんなチームにおすすめ / おすすめしないケース

こんなチームにおすすめ

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

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

• TypeScriptで新ハーネスのフル機能を使いたいチーム（v0.17.0からハーネス対応が開始されたが、サンドボックスはPythonが先行）
• モデルをAnthropic（Claude）やGoogle（Gemini）中心で組みたい場合
• 自社で厳密にハーネス挙動を制御したい研究開発用途（LangGraphのグラフDSLが向く場合あり）
• Code Modeの正式プリミティブが必須の要件がある（現状は未リリースのため代替実装が必要）
• サブエージェントのTypeScript版が必須（Python版ベータのみで、TypeScript対応は時期未定）
• 企業コンプライアンス要件で認証範囲が契約上明確になっていないと導入できないケース

よくある質問

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

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

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

v0.17.0でTypeScript版のオープンソースハーネス対応が追加されました。ただしサンドボックス機能はPythonが先行しています。TypeScript版のサンドボックス・サブエージェントの正式対応時期は現時点で未公表です。TS中心のチームは、当面は従来機能を使いつつ、Python側で先行検証する構成が現実的です。

Q3. サブエージェントとコードモードはいつ使えますか？

• サブエージェント: Python版ベータとして2026年4月15日から提供開始。APIや仕様はベータのため変更の可能性あり。TypeScript版は後日予定
• コードモード: 2026年6月18日時点で未リリース。発表済みだが公開日未定

現時点ではshell + apply_patchツール、handoffs、agents-as-tools、asyncio並列Runnerで代替実装するのが実務解です。

Q4. v0.16.0のデフォルトモデル変更で何に気をつけるべきですか？

v0.16.0でデフォルトモデルがgpt-4.1からgpt-5.4-miniに変更されました。コスト面では有利ですが、モデルが変わることでレスポンスの品質・特性が変化する可能性があります。既存のプロンプト・ガードレールの挙動を必ずテストしてから本番へ移行してください。

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

SDK自体は無料ですが、OpenAI API料金（gpt-5.4-miniで入力$0.75/1Mトークン、出力$4.50/1Mトークン）とサンドボックスプロバイダー料金が発生します。まずは小さなタスクで実測してから本番のコスト計算をするのが安全です。バッチAPIを使えば非同期処理（24時間以内）で標準料金の50%に抑えられます。

Q6. CVE-2025-6514への対応が必要ですか？

MCPプロキシライブラリmcp-remoteに影響するCVSS 9.6の脆弱性です。MCPサーバーと統合している場合は依存パッケージを最新版に更新してください。AIコーディングのセキュリティリスクも参照してください。

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

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

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

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

まとめ

• OpenAI Agents SDK 新ハーネスは、制御層と計算層を公式に分離した2026年4月の大型アップデートで、Pythonを中心に本格エージェント開発が一気にやりやすくなりました
• Manifest + SandboxClientでワークスペースと実行環境を宣言的に記述でき、9プロバイダーに公式対応しています
• サブエージェントはPython版ベータとして利用可能。コードモードは未リリースで、既存のhandoffs / agents-as-tools / shell / apply_patchで代替実装が可能です
• v0.16.0でデフォルトモデルがgpt-5.4-miniに変更されたため、既存実装の移行時は動作確認が必要です
• 本番導入では認証情報の取り扱い・承認ハンドラ・スナップショット運用・CVE-2025-6514への対応を最初に設計に組み込むのが安全です

エージェントフレームワーク全体の比較や、AIエージェントの基礎を理解したい場合は以下の関連記事も参考にしてください。

• AIエージェントとは？仕組み・できること・活用事例を解説
• AIエージェントフレームワーク おすすめ 比較
• AIエージェントのセキュリティ対策ガイド
• OpenAI Codex Labsとは
• Claude Managed Agentsとは

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

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