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

セッションの 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 と、 値が function_call または environment_connectionrequired_action.type が含まれます。

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

セッションを取得し、required_actions で呼び出し ID、引数、または環境 ID を確認してください。 Webhook にはこれらの詳細は含まれません。

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_IDdata.environment_id を、REMOTE_URLdata.connect.remote_url を設定してください。この URL は、セッションの environment.remote_url として返されるものと同じです。両方の値を保存し、再接続時に再利用してください。

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

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

イベントの検証と処理

OPENAI_API_KEYOPENAI_WEBHOOK_SECRET を設定してください。Python の場合は fastapiuvicornopenai をインストールしてください。JavaScript の場合は expressopenai をインストールしてください。

ハンドラーは署名を検証し、ポート 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 を追加します。接続を 待ち始める前にagent.session.action_required を発行します。

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

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

待機時間が終了すると、入力の送信は失敗します。初回入力は非同期で失敗し、セッションが failed 状態になる場合があります。接続待機の仕組みは、永続的な入力キューを提供するものではありません。プロセスがクラッシュした場合やクライアントが切断された場合は、再試行が必要になることがあります。

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

agent.session.idle はセッションが追加入力を受け付けられることを意味し、直前のターンが成功したことを意味するものではありません。そのターンのステータスを確認するか、セッションストリームの agent.session.turn.completedagent.session.turn.failedagent.session.turn.cancelled を監視してください。完了したターンにも、失敗したツール呼び出しが含まれている場合があります。ツールの結果とエージェントの最終応答を確認してください。

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