🧰 アプリケーションからCodexハーネスへ仕事を渡すOpenAI Agents API

Agents API は、アプリケーションから Codex ハーネスへ仕事を渡し、結果を受け取るマネージド API です。OpenAI がセッション、オーケストレーション、コンテキスト compaction、復旧を運用し、アプリケーションはツールと実行環境を選びます。

この記事では、公開ベータのコア概念、アーキテクチャ、データモデル、導入と利用、運用上の制約を一次資料に沿って整理します。読み終えると、Agents SDK や Responses API との役割分担と、セッションを実装するときにアプリケーション側へ残る責務がわかります。

本稿の対象は POST /v1/agents/sessions と SDK の client.beta.agents です。OpenAI Agents SDK（openai-agents / @openai/agents）、Responses API、Google Managed Agents は別ランタイムです。

本文の API 名・ヘッダ・コード例は、2026-09-11 時点の Agents API ガイド と 発表ブログ に照合しています。公開ベータのため、フィールド名と列挙値は今後変わり得ます。

この記事の全体像。以下、順に解説します。

OpenAI Agents APIとは

公開日は 2026-09-10 です。全開発者向けの公開ベータとして提供されています。ハーネスは Codex と ChatGPT で使っているものと同一系統で、OpenAI がホストし保守します。中核ロジックは公開コードベース openai/codex で確認できます。

エージェントはサンドボックス上でコード実行、ファイル編集、MCP 接続、成果物生成ができます。セッションは設定・ターン・アイテムを保持し、続きの作業を同じセッションで進めます。

公式のコア概念は次の 4 つです。

セッション開始から完了までの流れは次です。

1. セッションを作成し、エージェントと環境を構成する。
2. ユーザー入力でターンを開始する。
3. ストリームまたは Webhook で進捗を追う。
4. 同じセッションへ追加入力するか、作業中ターンを steer する。

ランタイム比較

公式「Compare agent runtime options」の列です。

公式「Choose your starting point」は、上記 3 つに ChatKit（埋め込みチャット）を並べます。Agents API の session、Agents SDK の session、Responses の conversation、サンドボックスは別資源です。クリーンアップは選んだランタイムの手順に従います。

Google Gemini Managed Agents は Vertex / Gemini 側のマネージド実行です。本 API の Codex ハーネスおよび /v1/agents/sessions とは非互換です。

ユースケース別の向き先

Agents API の公式ショーケースは次です。

公式発表（2026-09-10）の顧客コメントに載る数値は次です。独立検証値ではなく、発表時点の引用です。

主な特徴

• 長時間セッション: 発表は、数時間から数日規模の稼働を支えるインフラと、ファイル・コード・中間結果を置く環境が実用エージェントに必要だと述べます。セッションは途中から再開できます。SLA や上限時間の公式数値は、公開ベータ資料では確認できていません。
• 自動 compaction: セッションがコンテキスト上限に近づくと、ハーネスが先行コンテキストを自動 compaction し、継続に必要な情報を残します。Responses API の POST /responses/compact をアプリが呼ぶ機能ではありません。
• Tool search: 必要なツール定義を都度ロードします。トークンとコストを抑え、モデルのキャッシュを保ちます。Agents API の function は eager が既定です。tool_search と defer_loading で遅延ロードになります。
• Programmatic tool calling: モデルが JavaScript を書き、ホストした V8 上でツールを並列・連鎖・フィルタします。Agents API ではハーネス既定で有効です。
• Subagent: multi_agent で独立作業を並列 subagent に委任します。同時実行数の既定は 6（コーディネータ除く）です。
• 環境選択: openai_hosted、self_hosted、none を選べます。パートナー例は Blaxel、Cloudflare、Daytona、DigitalOcean、E2B、Modal、Oracle、Runloop、Vercel です。
• 課金: 公開ブログは Agents API 自体の追加手数料なしと述べます。課金は選択モデルの API 料金、OpenAI ツールの標準料金、OpenAI ホストサンドボックスのコンテナ標準料金です。
• OSS Codex ハーネス: モデル呼び出し・ツール・コンテキスト調整の中核は openai/codex です。API 側では OpenAI がそのハーネスを運用し、モデル投入に合わせて更新します。
• Skills / Vault / MCP: capability directories でスキルを発見し、Vault で OpenAI 起点 MCP の資格情報を分離します。

アーキテクチャ

公式 Architecture は 3 片です。Harness は OpenAI がホストする Codex インスタンスです。Environment はコマンドとファイルの実行場所です。Application server は製品とエージェントをつなぐ開発者側コードです。

システムコンテキスト図

環境が none のときは、組み込み Bash、apply-patch、ワークスペースファイル、executor MCP は使えません。ハーネスはリモート MCP を直接呼べます。関数ツールは開発者アプリが実行し、結果をハーネスへ返します。

コンテナ図

公式 3 片に、制御プレーンと通知経路を足した読み替えです。

開発者側

OpenAI

実行環境

外部

ストリームを閉じてもタスクはキャンセルされません。関数ハンドラが止まると、エージェントは結果待ちのままになります。自己ホストでは、executor がつながるまで作業は始まりません。接続待ちの上限は 5 分です。

コンポーネント図

Agents API 制御プレーン

Managed Codex harness

サブエージェントは MCP、資格情報、Web 検索、環境のファイルとコマンドを継承します。関数ツールはサブエージェントにありません。サブエージェント追加は環境を増やしません。コーディネータとサブエージェントは同一ファイルシステムを共有します。

環境選択と責務

自己ホストの公式制約です。

• 1 セッションにつき environment ID と executor は 1 組です。イメージと workspace_directory は再利用できます。
• environment_template_id は openai_hosted 専用です。
• executor キーはセッションと同一 organization / project / user または service account です。他権限は None です。
• パートナー手順は Modal、Cloudflare、Vercel、Daytona、Blaxel、E2B、Runloop、DigitalOcean、OCI の Sandbox providers に分かれます。

データ

概念モデル

所有は入れ子、利用は矢印です。

情報モデル

Item.type の確認済み値は次です。

message / reasoning / function_call / function_call_output / agent_message / mcp_call / web_search_call / command_execution / create_subagent_call / send_subagent_input_call / wait_for_subagents_call / interrupt_subagent_call / resume_subagent_call / close_subagent_call

ストリームの Event.type は streaming events が正本です。下表はガイドとリファレンスで確認した抜粋であり、全イベントではありません。

Webhook の待ちは agent.session.action_required です。ストリームの待ちは agent.session.requires_action です。

Session.required_actions の型は function_call（turn_id / call_id / name / arguments）と environment_connection（environment_id）です。

Usage のネスト対応は次です。

確認済みの制約です。

導入手順

前提（キー権限とヘッダ）

• Platform プロジェクトでアプリケーション API キーを作成します。
• セッション操作用に api.agents.read と api.agents.write を付与します。
• モデル推論用に api.responses.write を付与します。
• このキーはエージェントのサンドボックス外に置きます。

export OPENAI_API_KEY="your-api-key"

• リクエストは OpenAI-Beta: agents=v1 が必須です。
• OpenAI SDK はヘッダを自動付与します。
• cURL では明示します。

SDK インストール

パッケージは openai（beta.agents 名前空間）です。openai-agents は別ランタイムです。

pip install --upgrade openai

npm install openai

セッション作成（ホスト済みサンドボックス）

公式 quickstart のモデル名は gpt-6-astra です。利用可能なモデルはプロジェクトと時点で変わります。

from openai import OpenAI

with OpenAI() as client:
    with client.beta.agents.sessions.create(
        agent={
            "model": "gpt-6-astra",
            "instructions": "Write clean code, run it, and report the actual output.",
        },
        environment={"type": "openai_hosted"},
        input="Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
        stream=True,
    ) as events:
        for event in events:
            print(event.to_json(indent=None), flush=True)

curl --no-buffer --fail-with-body 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" },
    "input": "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
    "stream": true
  }'

• イベントの session_id（agent.session.created の session.id）を会話状態として保存します。
• environment.type: "none" のセッションは作成時に初期 input が必須です。
• 保存済みエージェントは client.beta.agents.create のあと agent_id でセッションに渡します。

agent = client.beta.agents.create(
    model="gpt-6-astra",
    instructions="Answer technical questions accurately.",
    reasoning={"summary": "auto"},
)
session = client.beta.agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    input="Explain how an agent connects to an MCP server.",
)

環境 3 種の初期セットアップ

openai_hosted で作成時に足せる設定です。

• packages: python / system / npm のリスト。必要ならバージョン固定（例: pandas==2.2.3）。
• setup_commands: エージェント開始前のシェル。各コマンドに任意の cwd（既定 /workspace）。
• files: Files API の file_id または inline base64。どちらも path 必須。
• env: 文字列の環境変数。PATH / CODEX_* / OPENAI_API_KEY は拒否。
• skills / plugins / capability_directories
• environment_template_id: 保存済み設定の再利用。ネットワーク上書きはテンプレートより広くできません。
• network.access: enabled（既定） / disabled / restricted

パッケージと入力ファイルは setup より先に準備されます。setup の非ゼロ終了はエージェント開始を止めます。作成応答は setup 開始を意味します。状態は GET /v1/agents/environments/{environment_id} で確認します。スキーマ上の setup 中は pending です。hosted ガイドの provisioning は同じ段階の説明語です。

自己ホスト executor の接続

環境内の準備です。

mkdir -p /workspace
npm install -g @openai/codex@alpha

outbound 先は次です。

• https://api.openai.com（環境登録）
• wss://codex-cloud-environments.chatgpt.com（コマンドと結果）

セッション作成はアプリケーション側（環境の外）です。

session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "You are a helpful coding assistant. Write clean code and verify that it works.",
    },
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
)

• session.environment.id と session.environment.remote_url を executor に渡します。
• remote_url は再接続時も含め変更しません。
• 環境へは restricted executor キーを CODEX_API_KEY として渡します。他権限は None です。

codex exec-server \
  --remote "<session.environment.remote_url>" \
  --environment-id "<session.environment.id>"

接続イベントは agent.session.environment.pending / connected / failed です。エージェントは接続済み環境とユーザー入力の両方が揃って作業を始めます。

利用方法

必須パラメータ

セッションの取得と削除

session = client.beta.agents.sessions.retrieve(session_id)
result = client.beta.agents.sessions.delete(session_id)

curl "https://api.openai.com/v1/agents/sessions/$session_id" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

curl -X DELETE "https://api.openai.com/v1/agents/sessions/$session_id" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

status が requires_action のとき、required_actions を処理します。

• function_call: 関数を実行し、同じセッションへ turn_id / call_id 付きで結果を返します。
• environment_connection: environment_id の環境を接続します。

追加入力とキャンセル

エンドポイントは POST /v1/agents/sessions/{session_id}/events です。アイドルなら新ターンです。作業中なら現ターンへの steer です。フォローアップ前にイベントストリームを購読します。

def send_message(client: OpenAI, session_id: str, text: str) -> None:
    client.beta.agents.sessions.events.create(
        session_id,
        events=[
            {
                "type": "agent.session.input.message",
                "input": [
                    {
                        "role": "user",
                        "content": [{"type": "input_text", "text": text}],
                    }
                ],
            }
        ],
    )


def cancel_turn(client: OpenAI, session_id: str) -> None:
    client.beta.agents.sessions.events.create(
        session_id, events=[{"type": "agent.session.input.cancel"}]
    )

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

完了判定はルートターンの終端イベントです。agent.session.turn.completed / failed / cancelled に加え、event.turn.subagent_id is None を確認します。サブエージェントの完了だけでは依頼全体の完了ではありません。agent.session.idle だけでは成功ではありません。

保存済み items / turns / artifacts

items = client.beta.agents.sessions.items.list(session_id, order="asc", limit=100)
turns = client.beta.agents.sessions.turns.list(session_id, limit=20, order="desc")
latest = next(iter(turns.data))
turn = client.beta.agents.sessions.turns.retrieve(latest.id, session_id=session_id)
print(turn.subagent_id)


def download_artifact(client, session_id, turn_id, path, destination):
    for artifact in client.beta.agents.sessions.artifacts.list(session_id):
        if artifact.turn_id != turn_id or artifact.path != path:
            continue
        with client.beta.agents.sessions.artifacts.with_streaming_response.content(
            artifact.id, session_id=session_id
        ) as response:
            response.stream_to_file(destination)
        return
    raise FileNotFoundError(path)

ルートエージェントの subagent_id は null です。openai_hosted だけ Artifacts API が /workspace/outputs を公開します。

MCP と function ツール

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

{
  "type": "function",
  "name": "get_customer",
  "description": "Look up a customer by ID.",
  "parameters": {
    "type": "object",
    "properties": { "customer_id": { "type": "string" } },
    "required": ["customer_id"],
    "additionalProperties": false
  }
}

関数結果は agent.session.input.tool_result で、同じ turn_id / call_id を返します。required_actions の要素は SDK ではオブジェクトなので、添字参照する前に to_dict() します。成功時の output は文字列、または input_text / input_image のコンテンツ配列です。通常の JSON データ（辞書など）は文字列化します。コンテンツ配列はそのまま渡します。

import json


def return_tool_result(client, session_id, action, output, success=True):
    action = action.to_dict() if hasattr(action, "to_dict") else action
    event = {
        "type": "agent.session.input.tool_result",
        "turn_id": action["turn_id"],
        "call_id": action["call_id"],
    }
    if success:
        if isinstance(output, list):
            event["output"] = output
        elif isinstance(output, str):
            event["output"] = output
        else:
            event["output"] = json.dumps(output)
        event["success"] = True
    else:
        event["success"] = False
        event["error"] = output
    client.beta.agents.sessions.events.create(session_id, events=[event])

履歴の function_call item だけでは未処理とは限りません。session.required_actions のエントリだけ処理します。

マルチエージェント

events = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": "Delegate each release to a separate subagent.",
        "multi_agent": {"enabled": True, "max_concurrent_subagents": 2},
    },
    environment={"type": "none"},
    input="Release A: ... Release B: ...",
    stream=True,
)

委譲ツールはハーネスが供給します。自分で宣言しません。

Skills（capability directories）

以下は capability directories でスキルを発見する方式です。Responses の hosted shell 向け skill_reference 添付形式は、この経路では使いません。openai_hosted では、セッション作成時の environment.skills で Skills API 参照（type: skill_reference）や inline ZIP も選べます。サンドボックス内の親ディレクトリを environment.capability_directories に登録します。最大 32、絶対パス、既存ディレクトリです。

{
  "environment": {
    "type": "self_hosted",
    "workspace_directory": "/workspace",
    "capability_directories": [
      "/workspace/capabilities/legal",
      "/workspace/capabilities/engineering"
    ]
  }
}

運用

状態確認

ターンは非同期です。成功判定は idle やストリーム切断では行いません。

ログとトレース

ライブ作業はイベントストリームです。詳細トレースは platform.openai.com/logs?api=agents の Agents タブです。公開ベータ API に tracing 設定、trace retrieval、外部 exporter はありません。プロジェクト API キーでは詳細トレースを取れません。

失敗系イベントは次です。

• agent.session.turn.failed
• agent.session.turn.cancelled
• agent.session.failed
• agent.session.environment.failed
• error

ストリーム切断復旧

ストリームは missed event を replay しません。

1. 新しいストリームを開き、到着イベントをバッファします。
2. ストリームを繋いだままセッションと items を retrieve します。
3. ローカル状態を item_id キーで items から復元します。
4. バッファした item 更新を item_id で適用します。履歴で最終状態に達した item への更新は破棄します。restore_from_items は、その確定済み item.id の集合を返します。
5. ライブイベント処理に戻ります。

def recover_disconnected_stream(client, session_id, handle_event):
    with client.beta.agents.sessions.events.stream(session_id) as events:
        session = client.beta.agents.sessions.retrieve(session_id)
        items = client.beta.agents.sessions.items.list(
            session_id, order="asc", limit=100
        )
        finalized = restore_from_items(items)
        if session.required_actions:
            handle_required_actions(session.required_actions)
        for event in events:
            item_id = getattr(event, "item_id", None)
            nested = getattr(event, "item", None)
            nested_id = getattr(nested, "id", None) if nested is not None else None
            if item_id in finalized or nested_id in finalized:
                continue
            handle_event(event)

イベントストリームを閉じてもタスクはキャンセルされません。止めるときは agent.session.input.cancel です。

セッション削除と 409

hosted で setup 中または実行中に delete すると 409 が返ることがあります。待ってから、試行回数の上限付きで再試行します。

import time


def delete_session_with_retry(client: OpenAI, session_id: str, attempts=5):
    delay = 1.0
    for _ in range(attempts):
        try:
            return client.beta.agents.sessions.delete(session_id)
        except Exception as exc:
            status = getattr(exc, "status_code", None)
            if status != 409:
                raise
            time.sleep(delay)
            delay = min(delay * 2, 16)
    raise TimeoutError(session_id)

self_hosted ではセッション削除とプロバイダ compute 停止は別操作です。削除 Webhook はありません。

サンドボックス keepalive

connected な hosted サンドボックスはターン間も含めて keepalive を受けます。アクティビティと keepalive が 1 時間止まると削除され得ます。このタイムアウトは設定できません。/workspace/outputs の公開コピーはサンドボックス期限切れ後もダウンロードできます。

Webhook で self_hosted の compute 起動

API は接続待ちの前に agent.session.action_required を出します。function_call の required action では compute を起動しません。agent.session.in_progress は実行開始の確認であり、接続待ちの合図ではありません。API の入力時接続待ちは最大 5 分です。クラッシュ後の pending input は replay されません。待機中に同じ input を再送しません。同一 environment ID の再接続は、差し替え compute のファイル復元を意味しません。プロバイダの snapshot が必要です。agent.session.idle は self_hosted compute 停止の合図ではありません。接続要求と実行中を再確認してから止めます。

購読イベントは created / action_required / in_progress / idle / failed です。

usage の扱い

セッションとターンの usage は best-effort です。未知のときは null です。記録値は後から変わります。欠落はゼロ消費ではありません。最終請求ではありません。

{
  "input_tokens": 5000,
  "input_tokens_details": { "cached_tokens": 1500 },
  "output_tokens": 900,
  "output_tokens_details": { "reasoning_tokens": 200 },
  "total_tokens": 5900
}

cache-write 回数は Agents API の usage フィールドにありません。ルートと subagent の両方を見ます。

ベストプラクティス

キー分離

• アプリキーをサンドボックス、イメージ、ソース、ログに入れません。
• hosted の environment.env に PATH、CODEX_*、OPENAI_API_KEY を含めません。
• 第三者資格情報は環境に置かず、ブローカー経由を優先します。
• ユーザー / ワークロードごとに環境と OpenAI プロジェクトを分けます。
• webhook 署名シークレットと executor key を混ぜません。

ネットワーク allowlist

• hosted は必要最小の restricted または disabled から始めます。
• restricted は完全一致ホスト名 1-100 件です。ワイルドカード、プロトコル、パス、ポートは使えません。
• hosted stdio MCP は現状 enabled が必要です。
• self_hosted の executor は api.openai.com と wss://codex-cloud-environments.chatgpt.com への outbound を許可します。
• テンプレートの network 上書きは、テンプレートより広いポリシーにできません。

ツール定義と prompt cache

• 初期 instructions とツール定義をむやみに変えません。
• 新しいタスク詳細はフォローアップメッセージに置きます。
• 大きいカタログだけ { "type": "tool_search" } と関数の defer_loading: true を使います。
• Programmatic Tool Calling の無効化だけ明示します。

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

独立タスクだけ subagent

• 独立タスク（別文書のレビュー、別原因の調査）に使います。
• 短い作業と依存ステップはメインエージェントに残します。
• 同一ファイルを編集するエージェントは変更を協調します。
• create / wait の完了は、subagent のタスク完了を意味しません。

成果物を削除前に保存

• openai_hosted はターン完了後に Artifacts API で保存します。
• self_hosted はプロバイダの file API またはマウント FS で保存します。
• セッション削除は残したい公開コピーより先にしません。

データ保持の前提を契約に書く

• Agents API の data residency は現時点で米国のみです。
• Zero Data Retention (ZDR) 非対応です。
• self_hosted を選んでも ZDR 適格になりません。
• /v1/agents は学習利用なし、abuse monitoring は 30 日、application state は削除までです。
• 顧客 compute にファイルを置いても、セッション状態は API 側に残ります。

関数ハンドラを必ず用意する

環境を付けても function tools はそこで自動実行されません。履歴の function_call item だけでは未処理とは限りません。required_actions を見ます。副作用のある関数は session / turn / call ID で結果を耐久保存します。

注意点

ドキュメントと実装の乖離

資料間の食い違い

発表のコード例とガイドの省略時既定、ストリームと Webhook のイベント名は矛盾ではなく、取り違えやすい差です。

公開ベータ時点の未確認事項

トラブルシューティング

症状から原因、対処の順で見ます。完了イベントと idle だけを成功判定に使いません。

• 環境失敗は environment.error を読んで別セッションでやり直します。
• ターン完了は全ツール成功を保証しません。items を照合します。
• ストリーム切断は items から復元します。missed event は再生されません。
• 関数待ちは required_actions を処理します。
• 自己ホストは executor 接続と compute 停止をアプリが担います。

環境とセットアップ

ターン結果とストリーム

関数と自己ホスト

観測とデータ制約

まとめ

Agents API は、アプリケーションから Codex ハーネスへ仕事を渡し、セッションとイベントで進捗を回収するマネージド実行面です。環境は none / openai_hosted / self_hosted の 3 種で、計算の所有者と成果物の取り出し方が変わります。

実装で先に決めるのは 4 点です。関数ツールの required_actions ハンドラ、ストリーム切断後の items 復元、hosted の 1 時間 idle、ZDR 非対応と米国レジデンシーです。成功判定は idle や切断ではなく、ターン終端イベントと保存済み items で行います。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

概要 / 構造

• Introducing the Agents API
• Agents API overview
• Architecture
• Compare agent runtimes
• openai/codex

データ / 構築 / 利用

• Quickstart
• Configuring Agents
• Run and continue sessions
• Events and items
• Agents streaming events
• Create session リファレンス
• OpenAI-hosted sandboxes
• Self-hosted sandboxes
• Files and artifacts
• Functions
• MCP connections
• Vaults
• Skills（Agents API）
• Multi-agent

運用 / 注意点 / トラブルシューティング

• Sandbox lifecycle
• Sandbox security
• Session webhooks
• Manage sessions
• Observability and usage
• Tracing
• Data controls
• Tool search
• Programmatic tool calling
• Compaction（Responses 専用）
• Pricing
• Logs → Agents