Akira

Posted on Oct 2 Originally published at apidog.com

OpenAI Agents APIの使い方

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でコンピューター使用機能を追加しました。

今すぐApidogを試す

この記事では、最初の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つの概念

Agents APIでは、次の4つを理解しておくと実装しやすくなります。

エージェント: モデル、指示、ツール、MCPサーバーの定義です。リクエストにインラインで渡すか、保存してagent_idを再利用します。
環境: エージェントがファイルを読み込み、コマンドを実行するための任意のサンドボックスまたはコンピューターです。
セッション: 設定、会話、保存済みの作業を維持する永続的なエージェントインスタンスです。
イベントとアイテム: イベントはリアルタイムの進捗通知、アイテムは保存済みメッセージやツール呼び出しです。

アイドル状態のセッションに送ったメッセージは新しいターンを開始します。一方、ターンの実行中に送るメッセージは、そのターンを操縦する入力として扱われます。

アーキテクチャページによると、ハーネスはモデルとツールのループを実行するホスト型Codexインスタンスです。コンテキスト圧縮もハーネスが処理するため、追加設定は不要です。

環境を選択する

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

none: 計算環境を使いません。リモートMCPサーバーと関数ツールは使えますが、組み込みBash、apply-patch、ワークスペースファイル、executor MCPは使えません。
openai_hosted: OpenAIがLinuxサンドボックスを管理します。/workspaceにはPythonとNode.jsが含まれます。container_sizeにはsmall（1 GB）、medium（デフォルト、4 GB）、large（16 GB）を指定できます。
self_hosted: 自分のラップトップ、コンテナ、リモートサンドボックスでcodex exec-serverを実行します。個別の環境キーでアウトバウンド接続します。

openai_hostedでは、ネットワークポリシーも指定します。

{
  "environment": {
    "type": "openai_hosted",
    "container_size": "small",
    "network": {
      "access": "restricted",
      "allowed_domains": ["example.com"]
    }
  }
}

network.accessにはenabled、disabled、またはallowed_domainsとともに使うrestrictedを指定できます。

/workspace/outputsに作成されたファイルは、ターン完了時にアーティファクトになります。キープアライブがないアイドル状態のサンドボックスは、1時間後に削除される場合があります。

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

REST経由で最初のセッションを作成する

まず、必要なパーミッションを持つキーを環境変数へ設定します。

export OPENAI_API_KEY="YOUR_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);

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

ストリーミングを使う

入力を送る前に、SSE接続を開いておくと初期イベントを取りこぼしません。

curl -N \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Accept: text/event-stream" \
  "https://api.openai.com/v1/agents/sessions/$SESSION_ID/events?stream=true"

監視対象となる主なイベントは次のとおりです。

テキスト出力: agent.session.turn.output_text.delta、agent.session.turn.output_text.done
ターン完了状態: agent.session.turn.completed、agent.session.turn.failed、agent.session.turn.cancelled
追加処理要求: agent.session.requires_action

agent.session.requires_actionは、関数結果、環境接続、コンピューター使用の承認が必要な場合に発生します。

実装時には次の点に注意してください。

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にMCPサーバーを追加します。

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

デフォルトではOpenAIが接続を開始します。つまり、connection_origin: "service"では、MCPサーバーがOpenAIから到達できなければなりません。

プライベートネットワーク上のサーバーにはconnection_origin: "environment"を使います。サンドボックス内でMCPサーバーを起動する場合はstdioを使います。

認証情報は次のいずれかで渡せます。

セッション単位でtransport.authorizationを渡す
vault_idsとともにボールト認証情報を関連付ける

ボールト認証情報としてはstatic_bearerまたはmcp_oauthを使用できます。

ツール検索を有効にする

モデルがツール検索をサポートしている場合、MCPツールは自動的に検出されます。多数の関数ツールを扱う場合は、tool_searchを追加し、遅延ロードする関数にdefer_loading: trueを指定します。

{
  "agent": {
    "tools": [
      { "type": "tool_search" },
      {
        "type": "function",
        "name": "get_customer",
        "defer_loading": true
      }
    ]
  }
}

プログラムによるツール呼び出し

プログラムによるツール呼び出しはデフォルトで有効です。エージェントは、分離されたV8ランタイムでJavaScriptを実行するexecツールを使えます。

これにより、エージェントはツール呼び出しをループしたり、大きなツール結果がコンテキストへ入る前に切り詰めたりできます。無効化する場合は次を指定します。

{
  "type": "programmatic_tool_calling",
  "enabled": false
}

サブエージェントを有効にする

サブエージェントを使うには、multi_agentを設定します。

{
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 3
  }
}

デフォルトの同時実行上限は6です。

サブエージェントは環境のファイルシステムを共有し、MCPツールとウェブ検索を継承します。ただし、関数ツールは使えません。ターンのsubagent_idは、メインエージェントの場合はnullです。

コンピューター使用を有効にする

コンピューター使用機能を使うと、エージェントはホスト型ブラウザを操作できます。ホスト型環境、デスクトップ、ツールを次のように設定します。

{
  "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種類があります。

browser_origin_access: originとreasonを表示し、approve、deny、またはcancelを送信します。
browser_authentication: fields、任意のログインoptions、credential_originを含むサインインフォームです。ユーザー入力とともにaction: "submit"を送信するか、action: "cancel"を送信します。

オリジンアクセスを承認するイベントの例です。

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"
        }
      }
    ]
  }'

ブラウザ操作はcomputer_use_callアイテムとして記録されます。このアイテムにはid、turn_id、title、status、outputが含まれます。

include_screenshotsが有効でスクリーンショットを取得できる場合、outputにはbase64エンコードされたJPEGスクリーンショットが含まれます。アカウントデータが表示される可能性があるため、スクリーンショットをログに残さないでください。

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

オリジン承認はアクション確認ではありません。 サイトを承認しても、購入や削除のたびに確認を求めるわけではありません。確認が必要なら、ブラウザをそのような操作を実行できないリソースに制限するか、自分で制御するブラウザランタイムを使用してください。
サインインはメール、パスワード、確認コードに対応します。 パスキーとQRコードによるサインインはサポートされません。
認証を要求できるのはメインエージェントだけです。 サブエージェントは認証を要求できません。
認証情報を送信するリクエストでは自動再試行を無効にします。 SDKではmaxRetries: 0、curlでは--retry 0を指定します。
202は承認済みを意味するだけです。 ナビゲーションやサインインの成功は意味しません。認証リクエストは5分後に期限切れになります。
オリジン承認はネットワークポリシーを上書きしません。 networkでも対象サイトとリダイレクト先ドメインを許可してください。

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

エージェントにはUIではなくAPIを提供する

ブラウザは、APIを持たないソフトウェアのフォールバックとして扱うべきです。自分で管理しているシステムなら、MCPサーバーでラップしてください。

MCP経由でAPIを提供すると、次の利点があります。

型付きツールを提供できる
ブラウザのオリジン承認が不要になる
検証可能な構造化結果を受け取れる

トレードオフはコンピューター使用と構造化APIの比較で確認できます。Apidog MCPサーバーは、API仕様をラッパー作成用のコーディングアシスタントに供給します。

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

Agents APIはベータ版です。実装前にApidogで各リクエストの形式とレスポンスを確認してください。

実施手順は次のとおりです。

OPENAI_API_KEY、VAULT_ID、SESSION_IDを含むApidog環境を作成します。
すべてのリクエストにBearer {{OPENAI_API_KEY}}とOpenAI-Beta: agents=v1を設定します。
まずstreamなしでセッション作成リクエストを送信します。2xxステータスと空でないidをアサートし、idをSESSION_IDへ抽出します。
SSEリクエストとしてイベントストリームを開き、別リクエストから入力を送信してイベントの到着を確認します。
承認・キャンセル用ペイロードを保存し、各required_actionsケースを再現できるようにします。
リクエストをテストシナリオへ連結し、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は、ループを構築するためのモデル呼び出しです。詳細はAgents API vs Responses API vs Agents SDKを参照してください。

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

最初は読み取り専用のセッションを作成してください。次にMCPサーバーを1つ追加し、最後にデフォルト拒否の承認ハンドラーの背後でコンピューター使用機能を有効化します。

ChatGPTが独自サーバーからのイベントへ反応する必要がある場合は、MCPイベントが対応する仕組みです。

DEV Community