Blog

OpenAI Agents APIの使い方

OpenAI Agents APIチュートリアル：curlでセッションを作成し、サンドボックスを選択し、MCPツールとサブエージェントを追加し、コンピュータ利用承認を処理する方法。料金と制限。

Medy Evrard

2 10月 2026

OpenAI Agents APIの使い方

Apidog エンタープライズ

オンプレミスデプロイ

SSO & RBAC

SOC 2 準拠

Apidog Enterpriseを見る

OpenAI Agents APIは、OpenAIのオープンソースCodexハーネスをユーザーのために実行します。`OpenAI-Beta: agents=v1`ヘッダー、エージェント定義、およびタスクを付けて`POST https://api.openai.com/v1/agents/sessions`を送信すると、OpenAIがモデルとツールループを実行し、セッションを維持し、サンドボックスをプロビジョニングできます。Agents APIに料金はかかりません。トークン、ツール、ホスト型コンテナの時間に対して支払いが発生します（1GBから16GBのサンドボックスサイズで、20分セッションあたり0.03ドルから0.48ドル）。これは2026年9月10日にパブリックベータ版になり、OpenAIは9月29日のDevDayでコンピューター使用機能を追加しました。

ボタン

以下：最初のRESTセッション、進捗イベント、MCPツール、サブエージェント、およびコンピューター使用の承認フロー。OpenAIの他のエージェントインターフェースとの比較については、Agents API vs Responses API vs Agents SDKをお読みください。イベントの残りの部分については、DevDay 2026のまとめをご覧ください。すべての呼び出しはプレーンなHTTPであるため、アプリケーションコードを記述する前にApidogから送信できます。

OpenAI Agents APIの概要

項目 値
ステータス 2026年9月10日からパブリックベータ版、コンピューター使用機能は9月29日に追加
セッションの作成 POST /v1/agents/sessions
ベータヘッダー OpenAI-Beta: agents=v1（OpenAI SDKが追加）
主要なパーミッション api.agents.read, api.agents.write, api.responses.write
料金 Agents API料金はなし。モデルトークンはAPIレート、ツールは標準レート（ウェブ検索は1,000回呼び出しあたり10ドル）
ホスト型コンテナ 20分セッションあたり0.03ドル（small, 1 GB）、0.12ドル（medium, 4 GB）、0.48ドル（large, 16 GB）
環境 none, openai_hosted, self_hosted
ドキュメントの例で使用されているモデル gpt-6-astra
データ管理 米国のみのデータレジデンシー。Zero Data Retention (ZDR) はなし
最大リクエストサイズ 4 MiB

出典: Agents APIの紹介、Agents APIの概要、および料金ページ。

4つの概念

ドキュメントでは、APIを以下の4つの要素を中心に構築しています。

アイドル状態のセッションに送信されたメッセージは新しいターンを開始し、ターン中に送信されたメッセージはそれを操縦します。ハーネス（アーキテクチャページによると、モデルとツールループを実行するホスト型Codexインスタンス）もコンテキストの圧縮を処理するため、設定は不要です。

環境を選択する

environment.typeはコマンドがどこで実行されるかを決定します。

ローンチ投稿では、サンドボックスパートナーとしてBlaxel、Cloudflare、Daytona、DigitalOcean、E2B、Modal、Oracle、Runloop、Vercelが挙げられており、セルフホストガイドにはAWS Lambda MicroVMsが追加されています。

REST経由で最初のセッション

上記のパーミッションを持つキーを`OPENAI_API_KEY`としてエクスポートし、小さなコンテナでクイックスタートタスクを送信します。

curl --no-buffer https://api.openai.com/v1/agents/sessions \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "model": "gpt-6-astra",
      "instructions": "Write clean code, run it, and report the actual output."
    },
    "environment": { "type": "openai_hosted", "container_size": "small" },
    "input": "Create tree.py, a script that prints a tree of the files in the current directory. Run it and show the output.",
    "stream": true
  }'

`stream: true`を使用すると、レスポンスは最初のターンのイベントストリームになります。そこからセッションIDを保存します。ライフサイクルの残りの部分では同じリソースを使用します。

アクション リクエスト
フォローアップまたは操縦 agent.session.input.messageイベントを含むPOST /v1/agents/sessions/{id}/events
アクティブなターンのキャンセル 同じエンドポイント、イベントタイプagent.session.input.cancel
保存された作業の読み取り GET /v1/agents/sessions/{id}/items?order=asc&limit=100
クリーンアップ DELETE /v1/agents/sessions/{id}

JavaScript SDKも同じ形状をとります。ローンチ投稿から採用されたこのバージョンは、ツール、サブエージェント、およびボールトを追加します。

import OpenAI from "openai";

const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [{ type: "web_search" }],
    multi_agent: { enabled: true, max_concurrent_subagents: 3 },
  },
  vault_ids: [process.env.VAULT_ID],
  environment: { type: "openai_hosted" },
  input: "Summarize breaking changes in the latest release notes.",
});
console.log(session.id);

進捗の追跡：ストリームまたはウェブフック

ストリーミング。入力を送信する前に、`Accept: text/event-stream`とともに`GET /v1/agents/sessions/{id}/events?stream=true`を開くことで、初期イベントを見逃さないようにします。以下のイベントに注意してください。

3つの落とし穴: agent.session.idleはターンが成功したことを意味せず、完了したターンでも失敗したツール呼び出しが含まれる可能性があり、ストリームを閉じてもタスクは停止しません。ストリームは見逃したイベントをリプレイしないため、切断後は新しいストリームを開き、セッションとそのアイテムを取得してください。

ウェブフック。agent.session.created、agent.session.action_required、agent.session.in_progress、agent.session.idle、およびagent.session.failedを購読します。命名に注意してください。ストリームはrequires_actionと表示しますが、ウェブフックはaction_requiredと表示します。ペイロードには呼び出しの詳細が含まれないため、ハンドラーはセッションを取得し、required_actionsを読み取ります。各署名を検証してください（ウェブフック署名検証）。長時間実行されるAPI操作は、なぜウェブフックが数分かかるタスクに適しているかを説明しています。

MCPツール、ツール検索、プログラムによるツール呼び出し、およびサブエージェント

MCP。`agent.tools`にサーバーを追加します。

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": { "type": "http", "server_url": "https://developers.openai.com/mcp" },
  "required": true
}

デフォルトではOpenAIが接続を行います（connection_origin: "service"）ので、サーバーはOpenAIから到達可能である必要があります。プライベートネットワークサーバーにはconnection_origin: "environment"を使用するか、サンドボックスで起動するにはstdioを使用します。認証情報には、1つのセッションにtransport.authorizationを渡すか、vault_idsとともにボールト認証情報（static_bearerまたはmcp_oauth）を添付します。

ツール検索。モデルがツール検索をサポートしている場合、MCPツールは自動的に検出されます。多数の関数ツールの場合、{"type": "tool_search"}を追加し、関数をdefer_loading: trueとマークします。

プログラムによるツール呼び出し。デフォルトで有効: エージェントは分離されたV8ランタイムでJavaScriptを実行するexecツールを取得し、ツール呼び出しをループしたり、大きな結果がコンテキストに到達する前にトリミングしたりできます。{"type": "programmatic_tool_calling", "enabled": false}で無効にできます。

サブエージェント。`multi_agent: {"enabled": true, "max_concurrent_subagents": 3}`を設定します（デフォルトの制限は6です）。サブエージェントは環境のファイルシステムを共有し、MCPツールとウェブ検索を継承しますが、関数ツールは使用できません。ターンのsubagent_idはメインエージェントの場合nullになります。

コンピューター使用：DevDayで追加された機能

コンピューター使用機能により、エージェントはホスト型ブラウザを利用できるようになります。ホスト型環境にツールとデスクトップを追加します。

{
  "agent": {
    "model": "gpt-6-astra",
    "tools": [{ "type": "computer_use", "include_screenshots": true }]
  },
  "environment": {
    "type": "openai_hosted",
    "desktop": { "enabled": true },
    "network": { "access": "enabled" }
  }
}

ブラウザは、パブリックサイトを含む新しいウェブサイトのオリジンにアクセスする前に、ユーザーの承認を必要とします。agent.session.requires_actionが発生したら、セッションを取得し、computer_use_approval_requestエントリを探します。ネストされたrequest.typeは次の2種類のいずれかです。

どちらの回答もイベントエンドポイントを通じて返されます。

curl "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{
    "type": "agent.session.input.computer_use_approval_request_result",
    "request_id": "REQUEST_ID",
    "response": { "type": "browser_origin_access", "decision": "approve" }
  }]}'

ブラウザの作業は、id、turn_id、title、status、およびoutputを持つcomputer_use_callアイテムとして表示されます。include_screenshotsがオンでスクリーンショットが利用可能な場合、outputにはbase64 JPEGスクリーンショットが含まれます。スクリーンショットはログに残さないでください。アカウントデータが表示される可能性があります。

コンピューター使用ガイドでは、以下の注意点が指摘されています。

まとめによると、コンピューター使用機能は「API、およびCodex、Pro 500およびEnterprise向けのChatGPT Workを通じて」提供されます。同じモデルを使用したUI駆動テストについては、APIテストのためのGPT-6 Astraコンピューター使用をご覧ください。

エージェントにはUIではなくAPIを提供してください

ブラウザはAPIを持たないソフトウェアのフォールバックです。システムがあなたのものである場合、MCPサーバーでラップしてください。これにより、型付きツール、オリジンプロンプトなし、確認可能な結果が得られます。コンピューター使用と構造化APIの比較ではトレードオフについて説明されており、Apidog MCPサーバーは、API仕様をラッパーを作成するコーディングアシスタントに供給します。

コードを書く前にApidogでAgents APIをテストする

APIはベータ版であるため、コードを記述する前に、Apidogで各呼び出しの形状を手動で確認してください。

  1. OPENAI_API_KEY、VAULT_ID、SESSION_IDを使用してApidog環境を作成します。すべてのリクエストでBearer {{OPENAI_API_KEY}}とOpenAI-Beta: agents=v1を送信します。
  2. streamなしでセッション作成リクエストを送信し、2xxステータスと空でないidをアサートし、idをSESSION_IDに抽出します。
  3. SSEリクエストとしてイベントストリームを開き、2番目のリクエストから入力を送信し、イベントが到着するのを確認します。
  4. 承認およびキャンセルペイロードをリクエストとして保存し、各required_actionsケースをリプレイします。
  5. それらをテストシナリオに連結し、Apidog CLIを使用してCIで実行します。

AIエージェントAPIテストガイドには、非決定的な出力のアサーションパターンがあります。Apidogをダウンロードして続けてください。

よくある質問

OpenAI Agents APIは無料ですか？ プラットフォーム料金はかかりませんが、モデルトークン、ツール呼び出し、ホスト型コンテナの時間に対して料金が発生します。

Agents APIはどのモデルで動作しますか？ ドキュメントの例では、すべてのコンピューター使用例を含め、gpt-6-astraを使用しています。他のサポートされているモデルはリストされていないため、まずご自身のモデルでテストしてください。

Agents APIはZero Data Retentionをサポートしていますか？ いいえ。米国のみのデータレジデンシーをサポートしており、セルフホスト型サンドボックスを使用してもZDRの対象ではありません。

Agents SDKまたはResponses APIとはどう異なりますか？ SDKはアプリ内でループを実行し、Responses APIはループを構築するモデル呼び出しです。詳細な比較をご覧ください。

まずは読み取り専用セッションから始める

まずは読み取り専用のセッションから始め、MCPサーバーを1つ追加し、次にデフォルトで拒否する承認ハンドラーの背後にコンピューター使用機能を追加します。ChatGPTが代わりに独自のサーバーからのイベントに反応すべき場合は、MCPイベントがその対応する部分です。

ApidogでAPIデザイン中心のアプローチを取る

APIの開発と利用をよりシンプルなことにする方法を発見できる

無料会員登録ダウンロード