OpenAI Agents APIを使用すると、1回のセッション作成呼び出しで耐久性のあるクラウドエージェントを起動でき、OpenAIがクラウドでエージェントハーネスを実行します。Novita Sandboxは、Agents APIやそのOpenAI管理ハーネスを置き換えるものではありません。これは、OpenAIが文書化しているセルフホステッド実行パス用の、分離されたステートフルなランタイムを提供します。アプリケーションがサンドボックスをセッションに接続し、エージェントがそのランタイム内でコマンドを実行したりファイルを編集したりし、アプリケーションがサンドボックスのライフサイクルを所有します。この分割は、OpenAIホストのエージェントワークフローが必要だが、コード、ファイル、ブラウザ、コンピュータ使用、長時間実行作業用の別個の再利用可能な環境が必要な場合に重要です。
このガイドでは、APIの主要な概念、ハーネスと環境の責任分担、セルフホステッドパスへのNovita Sandboxの接続方法、プロトタイプから本番環境に移行する前に確認すべき点について説明します。製品ページのみが必要な場合は、Novita Sandboxが最適な出発点です。
Agents API、Agents SDK、Responses API
OpenAIのエージェントランタイム比較は、3つの統合モデルを区別しています。
| やりたいこと | 使用するもの | 状態を管理するもの |
|---|---|---|
| OpenAI管理のCodexハーネスを通じて長時間実行タスクを実行する | Agents API | 保存されたセッション構成、ターン、アイテム |
| アプリケーション内でエージェントループを維持する | Agents SDK | アプリケーションの状態、SDKセッション、またはResponses会話 |
| モデルを直接呼び出し、すべてを自分で調整する | Responses API | アプリケーションの履歴またはResponses会話 |
Agents APIは最も高レベルのオプションです。OpenAIはこれを、OpenAI管理のAPIを通じてCodexハーネスにアクセスするものと説明しています。セッション、オーケストレーション、コンテキスト圧縮、復旧を処理します。Agents SDKはアプリケーション内で実行され、デプロイメント、ストレージ、承認、ランタイム統合をより細かく制御できます。Responses APIはモデルレイヤーに最も近いものです。この分割が有用なのは、「エージェント」が再利用可能なモデル/ツール構成を意味する場合もあれば、耐久性のある実行中のエージェントを意味する場合もあるためです。APIドキュメントでは、各ランタイムでこれらの用語が異なる方法で使用されています。
エージェントハーネスとは？
エージェントハーネスは、エージェントターンを中心としたクラウドサービスです。モデルに指示とコンテキストを送信し、ツールを呼び出し、進捗を追跡し、中断と再開を処理し、作業を検査可能なストリームに整理します。Agents APIでは、そのハーネスは管理されたCodexハーネスです。
管理されたハーネスは以下をサポートします：
- 環境がアタッチされている場合のコマンドとコードの実行。
- 関連するスキルと指示の適用。
- ツールまたはMCPを通じた外部データへの接続。
- 作業中のエージェントの誘導。
- コンテキストウィンドウを管理するための以前の作業の要約。
- 作業をサブタスクに分割し、サブエージェントに委任。
- 中断した場所からのセッション再開。
これは、アプリケーションが不要になるという意味ではありません。アプリケーションは引き続きセッションを作成し、入力を送信し、イベントを受信し、承認や関数呼び出しを処理し、IDやアーティファクトの保存方法を決定します。ハーネスはオーケストレーション作業を削減しますが、プロダクトポリシーを排除するものではありません。
エージェントにサンドボックスが必要な理由
一部のエージェントは、ファイルシステムに触れずに質問に答えたりリモートAPIを呼び出したりします。その他のエージェントは、ファイルの作成、依存関係のインストール、スクリプトの実行、ブラウザの検査、デスクトップの制御、ユーザーが離れている間のマルチステップタスクの維持が必要です。サンドボックスは、これらのアクションがプロダクトサーバーやローカルマシンに触れるのではなく、交換可能な実行環境を提供します。
Agents APIは環境をオプションとして扱います。OpenAIのアーキテクチャドキュメントは3つの実行選択肢をサポートしています：
none— ハーネスにはシェルもファイルシステムもありません。関数ツールは結果をハーネスに返します。openai_hosted— OpenAIがサンドボックスをプロビジョニングして管理します。self_hosted— アプリケーションが環境を起動して接続するため、独自のコンピューティング、プライベートネットワーク、カスタムソフトウェアを使用できます。
ここが2つのシステム間の境界が最も明確な部分です。Agents APIとOpenAIはハーネスをホストできますが、セルフホステッド環境ではチームが実行プラットフォームを選択できます。この選択は、分離、ファイルシステムの形状、ネットワーキング、SDK、一時停止/再開動作、課金、および維持するインフラストラクチャの量に影響します。
このアーキテクチャにおけるNovita Sandbox
Novita Sandboxは、AIエージェント向けのマネージド実行環境です。公式概要では、インフラストラクチャ管理なしでコードの実行、依存関係のインストール、ファイルへのアクセス、ブラウザの使用、セッション間での状態の保持を行うための、分離されたステートフルランタイムについて説明しています。直接的なNovitaのみのエージェントスタックでは、アプリケーションがサンドボックスを作成し、モデルまたはエージェントフレームワークがツール呼び出しを選択し、サンドボックスがそれらを実行し、アプリケーションはランタイムの外部でポリシー、承認、ストレージを保持します。
Agents APIに関しては、推奨される正確なフレームワークはネイティブではなく補完的です。OpenAIの現在のセルフホステッドサンドボックスガイドでは、Cloudflare、Daytona、DigitalOcean、E2B、Blaxel、Modal、Runloop、OCI、Vercelが文書化されたプロバイダーとしてリストされています。Novita Sandboxは現在そのプロバイダーリストには含まれていません。したがって、実用的なパスは、Novitaをアプリケーション管理の実行環境として使用し、OpenAIのセルフホステッド環境コントラクトを通じてAgents APIセッションに接続することです。これにより、有用な分離が維持されます。OpenAIは耐久性のあるハーネスを実行し、Novita Sandboxはランタイムを提供します。これは、現在のドキュメントでサポートされていない公式プロバイダー統合を主張することはありません。
Novita Sandboxは5つの概念に基づいて構築されています：
| 概念 | エージェントに与えるもの |
|---|---|
| Sandbox | 独自のファイルシステムとプロセススペースを持つ分離されたランタイム |
| Template | 再現可能な開始イメージ、依存関係、構成、セットアップ |
| Snapshot | 保存されたサンドボックス状態で、繰り返しのセットアップを回避するために再利用可能 |
| Secret | チームスコープの暗号化された値で、ハードコーディングされた認証情報を回避 |
| Region | 現在のUS v1/v2エンドポイントの場所 |
ランタイムは、コーディングエージェント、ブラウザエージェント、データ分析、リサーチ、RLスタイルのワークロードをサポートしています。Novita Sandbox概要は、現在のリージョンとライフサイクル動作の情報源です。
ライフサイクル、永続性、長時間実行作業
Novita Sandboxには、実行中、一時停止、強制終了の3つのライフサイクル状態があります。実行中のサンドボックスはコマンドを実行し、接続を提供できます。一時停止中のサンドボックスは、実行中のプロセスや変数を含むファイルシステムとメモリ内の状態を保存し、CPUとRAMの課金は停止します。ネットワーク接続は再開まで中断されます。強制終了されたサンドボックスは終了され、復元できません。
2つのタイムアウト制御が遷移を駆動します。サンドボックスタイムアウトは作成からカウントダウンし、アイドルタイムアウトは構成された期間クライアントが接続されていない場合に発火します。いずれのイベントでも、強制終了ではなく一時停止を選択でき、オプションで自動再開を有効にできます。これは、レビューを待つコード編集タスク、ステップ間で一時停止するブラウザセッション、依存関係と変数をそのまま保持して後で再開するデータ分析ノートブックに役立ちます。
スナップショットは一時停止とは異なります。一時停止はそのインスタンスの現在のサンドボックス状態を保持します。スナップショットは状態を再利用可能な環境としてキャプチャするため、新しいサンドボックスはインストール済みの依存関係、構成、ファイルがすでに存在する状態で起動できます。本番環境では、繰り返し可能なベースイメージにはテンプレート、再利用可能な作業状態にはスナップショット、認証情報はテンプレートやスナップショットに焼き付けるのではなくシークレットを使用してください。
Novitaをセルフホステッドパスに接続する
OpenAIのセルフホステッドサンドボックスガイドは、接続の形状を定義しています。アプリケーションは environment.type: "self_hosted" でセッションを作成し、環境IDとリモートURLを受け取り、ランタイム内でエグゼキュータを起動し、セッションを接続済みとして報告します。公式エグゼキュータコマンドは次のとおりです：
codex exec-server \
--remote "<session.environment.remote_url>" \
--environment-id "<session.environment.id>"
セッションイベントストリームは、agent.session.environment.pending、connected、または failed を報告します。エージェントが作業している間はエグゼキュータを実行したままにし、コンピューティングを停止する前にシャットダウンを調整する必要があります。
次のスケッチは、公式Novita SDKを使用したそのフローのNovita側を示しています。サンドボックスを作成し、ソースコードにシークレットを入れずに認証を準備し、OpenAIエグゼキュータを起動する場所を提供します。エグゼキュータキーを注入しイベントストリームを待機する正確な方法は、アプリケーションとOpenAI SDKのバージョンによって異なります。
import os
from novita_sandbox import Novita
def create_agent_runtime() -> str:
novita = Novita(api_key=os.environ["NOVITA_API_KEY"])
sandbox = novita.sandbox.create(
"codex",
timeout=3600,
envs={"CODEX_API_KEY": os.environ["CODEX_EXECUTOR_KEY"]},
)
try:
sandbox.git.clone(
"https://github.com/your-org/your-repo.git",
path="/home/user/repo",
username="x-access-token",
password=os.environ["GITHUB_TOKEN"],
depth=1,
)
print(
"Create the Agents API session with environment.type=self_hosted, "
"then start codex exec-server here."
)
except Exception:
sandbox.kill()
raise
return sandbox.sandbox_id
本番環境でこのパスを使用する前に、OpenAIのセルフホステッドサンドボックスガイドに対して、現在のOpenAI SDKオブジェクト、環境キー名、リモートURLの動作、ライフサイクル要件を確認してください。セッションAPIがサンドボックスを管理してくれると想定しないでください。self_hosted の場合、その責任は明示的にあなたにあります。
よりシンプルな非Agents-APIワークフローの場合、NovitaのCodexエージェントガイドでは、codex テンプレート上でCodex CLIを直接実行し、その出力をストリーミングし、完了時にサンドボックスを強制終了する方法が示されています。
セキュリティと認証情報
ハーネス、サンドボックス、アプリケーションサーバーを別々の信頼ドメインとして扱います。
- OpenAI APIキー、Novita APIキー、Gitトークン、データベース認証情報は、プロンプトやソースファイルの外部に保持します。
- サンドボックス内で使用されるチームスコープの機密値には、Novita Sandbox Secretsを使用します。
- OpenAIのガイダンスがサンドボックスの外部に属するとしている認証情報には、OpenAI vaultsを使用します。
- 安全なサンドボックスアクセスを優先します。Novitaのドキュメントでは、SDKバージョン2.0.0以降で作成されたサンドボックスでは安全なアクセスが自動的に有効になるとされています。古いカスタムテンプレートは再ビルドが必要な場合があります。
- 明示的なネットワークポリシーを設定し、タスクに必要な場合にのみ拡大します。
- 生成されたコードとアーティファクトは、より広い権限を受け取ったり本番システムに到達する前にレビューします。
これらの制御は連携して機能します。サンドボックスは生成されたコードの爆発半径を減らしますが、エージェントを承認したり、意図を検証したり、どのアーティファクトがランタイムを離れられるかを決定したりするものではありません。
コストと制限
OpenAIは、Agents APIのモデル使用量を選択したモデルのAPIレートで、OpenAIツールを標準レートで請求します。OpenAIホスト環境の場合、コンテナレートが適用されます。セルフホステッドパスの場合、実行リソースはプロバイダーのコストとなります。
Novita Sandboxの課金は、サンドボックス実行中のCPUとRAMに対して秒単位です。一時停止するとCPUとRAMの課金は停止します。一時停止中のデータは永続ストレージとして保持されます。各アカウントには60GBの無料永続ストレージが含まれ、追加ストレージは時間単位で課金されます。実行中の各サンドボックスには20GBのエフェメラルストレージが含まれます。公式サンドボックスクレジットと価格は変更されるため、Novita Sandbox価格ページで現在の値を確認してください。
並列ワークロードには、Novitaのクォータ制限も重要です。本稿執筆時点では、無料アカウントのデフォルトは5個の同時サンドボックス、有料アカウントは100個です。単一サンドボックスの最大vCPUとメモリはティアによって異なります。エンタープライズ制限は調整可能です。マーケティングページの例に頼るのではなく、クォータ制限ガイドと Sandbox.get_quota() を確認してください。
このアーキテクチャが適している状況
セルフホステッドNovitaランタイムは、以下の場合に適しています：
- エージェントがコードの実行、ファイルの変更、依存関係のインストール、テストの実行、Webの閲覧、デスクトップとの対話を行う必要がある場合。
- アプリケーションが人間の遅延、リトライ、マルチステップレビューにわたるステートフルセッションを必要とする場合。
- プロダクトサーバーとは別の分離された実行を希望する場合。
- ワークロードがテンプレート、スナップショット、一時停止/再開、または再現可能な環境から恩恵を受ける場合。
以下の場合は適していません：
- タスクがリモート関数呼び出しのみを必要とし、ファイルシステムやシェルが不要な場合。
- OpenAI管理の環境が必要で、環境ライフサイクルを所有したくない場合。
- OpenAIの現在の直接サンドボックスプロバイダーガイドにリストされているプロバイダーが必要な場合。
- コンプライアンスモデルが、Novitaがデプロイメントに対して文書化していないプロバイダー管理の分離制御を必要とする場合。
最も安全な評価は、実際のリポジトリ、コマンド、ネットワークポリシー、シークレット処理、障害パスを使用した小さな概念実証です。その後、起動、一時停止/再開、タスク完了、代表的な実行の総コストを測定します。
FAQ
Q: Novita SandboxはOpenAI Agents APIとネイティブ統合されていますか？
A: OpenAIの現在の環境プロバイダーガイドによれば、そうではありません。正確なアーキテクチャは、Agents APIのセルフホステッド環境パスを使用し、アプリケーション管理ランタイムとしてNovita Sandboxを起動し、その中で文書化されたエグゼキュータを実行することです。プロバイダー統合は変更される可能性があるため、リリース前に現在のガイドを確認してください。
Q: OpenAIがホスト型サンドボックスを提供している場合、それでもNovitaは必要ですか？
A: 要件によります。OpenAIのホスト型サンドボックスは低運用パスです。Novita Sandboxは、カスタムイメージ、テンプレート、スナップショット、ブラウザやコンピュータ使用のワークフロー、ステートフルな一時停止/再開、リソースのプロバイダーレベルの制御など、別のランタイム選択肢が必要な場合に役立ちます。
Q: エージェントは一時停止をまたいでプロセスやファイルを保持できますか？
A: はい。Novitaの一時停止/再開ドキュメントによると、実行中のプロセスや変数を含むファイルシステムとメモリ内の状態が保存されます。ネットワーク接続はサンドボックスが再開するまで中断されます。
Q: これはOpenAI Agents SDKと同じですか？
A: いいえ。Agents SDKはアプリケーション内で実行され、エージェントループをより細かく制御できます。Agents APIはOpenAIの管理されたCodexハーネスを使用します。Novita Sandboxはいずれのパターンの実行もホストできますが、セッションとオーケストレーションの動作は異なります。
Q: どこから始めればよいですか？
A: OpenAI Agents APIのクイックスタートを試して、ハーネスセッションとイベントを理解してください。次にNovita Sandboxを作成し、そのランタイム、ライフサイクル、セキュリティ、コストモデルが本番環境のニーズに合うかどうかを判断します。
