For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
メインナビゲーション
Theme

セッションの Webhook

エージェントのライフサイクルにおける状態変化に応答します。

Webhook を使うと、イベントストリームを開いたままにせずに、セッションの状態変化に応答できます。Webhook ハンドラーでは、サンドボックスのコンピューティング環境を起動したり、そこに再接続したりできます。アプリケーションの更新やワークフローの起動も可能です。

対応イベント

イベント 発生するタイミング
agent.session.created セッションが作成されたとき
agent.session.action_required セッションで関数の実行結果、環境への接続、またはコンピューターの使用に対する承認が必要になったとき
agent.session.in_progress セッションがターンの処理を開始したとき
agent.session.idle セッションがアイドル状態になり、次の入力を受け付けられるようになったとき
agent.session.failed セッションが失敗状態に移行したとき

agent.session.action_required イベントにはセッション ID と required_action.type が含まれます。後者の値は function_call、environment_connection、computer_use_approval_request のいずれかです。

{
  "type": "agent.session.action_required",
  "data": {
    "id": "sess_abc123",
    "required_action": { "type": "function_call" }
  }
}

セッションを取得し、required_actions で呼び出し ID、引数、環境 ID、またはコンピューターの使用に関する承認の詳細を確認します。これらの情報は Webhook に含まれません。コンピューターの使用では、ネストされた request.type で、ブラウザのオリジンへのアクセスを求めるリクエストか、認証を求めるリクエストかを判別できます。現在のリクエストをユーザーに表示し、ユーザーの回答をセッションイベントのエンドポイント経由で返します。リクエストとレスポンスの形式については、コンピューターの使用を参照してください。

Webhook の設定

共通の Webhook 設定ガイドに沿ってエンドポイントを作成し、Agents API のイベントを選択します。署名の検証に使うため、エンドポイントの署名シークレットを保存してください。

イベントの受信

購読しているイベントが発生するたびに、OpenAI は署名付きの HTTP POST リクエストを送信します。

{
  "id": "evt_123",
  "object": "event",
  "created_at": 1750287018,
  "type": "agent.session.created",
  "data": {
    "id": "sess_abc123",
    "environment_id": "ccarenv_abc123",
    "environment_type": "self_hosted",
    "connect": {
      "remote_url": "https://api.openai.com/v1/agents/api"
    }
  }
}

サンドボックスをプロビジョニングする前に、セッションの現在の状態を取得してください。詳しくは、サンドボックスのライフサイクルを参照してください。

エグゼキューターの起動

セルフホスト型のセッションでは、agent.session.created にエグゼキューターの起動に必要な環境 ID と接続 URL が含まれます。ENVIRONMENT_ID には data.environment_id の値を、REMOTE_URL には data.connect.remote_url の値を設定します。この URL は、セッションの environment.remote_url として返される URL と同じです。両方の値を保存し、再接続時にも使用してください。

CODEX_API_KEY="$OPENAI_ENVIRONMENT_KEY" \
codex exec-server \
  --remote "$REMOTE_URL" \
  --environment-id "$ENVIRONMENT_ID"

環境キーを CODEX_API_KEY として使用します。アプリケーションの API キーは環境の外部で管理してください。

イベントの検証と処理

OPENAI_API_KEY と OPENAI_WEBHOOK_SECRET を設定します。Python の場合は fastapi、uvicorn、openai を、JavaScript の場合は express と openai をインストールします。

ハンドラーはポート 8000 でリクエストを待ち受け、署名を検証します。ポートを変更するには PORT を設定します。本番環境では、時間のかかる処理をキューに入れてください。

Webhook ハンドラー
import json
import os

import uvicorn
from fastapi import FastAPI, Request, Response
from openai import AsyncOpenAI, InvalidWebhookSignatureError

app = FastAPI()
webhooks = AsyncOpenAI(webhook_secret=os.environ["OPENAI_WEBHOOK_SECRET"])


@app.post("/webhooks/openai")
async def handle_webhook(request: Request):
    payload = await request.body()
    try:
        webhooks.webhooks.verify_signature(payload=payload, headers=request.headers)
    except (InvalidWebhookSignatureError, ValueError):
        return Response("Invalid signature", status_code=400)

    event = json.loads(payload)
    if event["type"] == "agent.session.idle":
        session_id = event["data"]["id"]
        session = await webhooks.beta.agents.sessions.retrieve(session_id, timeout=10)
        print("session idle event:", session.id)
    else:
        print("session event:", event["type"], event["data"]["id"])
    return Response(status_code=200)


if __name__ == "__main__":
    uvicorn.run(app, port=int(os.environ.get("PORT", "8000")))

環境への接続に関するイベント

初回または追加の入力の処理に、未接続のセルフホスト型エグゼキューターが必要な場合、API は environment_connection を必須アクションに追加します。API が agent.session.action_required を発行するのは、接続待ちに入る前です。

セッションを取得し、required_actions で接続が引き続き求められていることを確認します。session.environment.id と session.environment.remote_url を使ってエグゼキューターを起動します。この Webhook には connect.remote_url は含まれません。待機時間内にエグゼキューターが接続すると、API は必須アクションを解除し、送信済みの入力の処理を再開します。クライアントによる再送信は不要です。

API は接続を最大 5 分間待ちます。その間、追加入力のリクエストは応答待ちのままになることがあります。この待機時間を考慮して、クライアントとプロキシのタイムアウトを設定してください。agent.session.in_progress は実行が始まったことを示します。API が接続を待っていることを示すものではありません。

待機時間内に接続できなければ、送信済みの入力の処理は失敗します。初回入力の処理は非同期で失敗することがあり、その場合、セッションは failed 状態になります。接続を待つ仕組みには、入力を永続化するキューはありません。プロセスがクラッシュしたり、クライアントの接続が切れたりした場合は、再試行が必要になることがあります。

セッションとターンの結果

agent.session.idle は、セッションが次の入力を受け付けられることを示します。直前のターンが成功したとは限りません。そのターンのステータスを調べるか、セッションストリームで agent.session.turn.completed、agent.session.turn.failed、agent.session.turn.cancelled のいずれが発生したかを確認してください。完了したターンにも、失敗したツール呼び出しが含まれることがあります。ツールの実行結果とエージェントの最終応答を確認してください。

agent.session.failed はセッションの失敗を通知します。ターンが失敗するたびに通知されるわけではありません。セッションの削除に対応する Webhook はありません。また、セッションを削除しても、プロバイダー側のコンピューティングリソースは停止しません。