トラブルシューティング

サポート対象環境

OpenAI Agents SDK は、次のサーバー環境でサポートされています:

• Node.js 22+
• Deno 2.35+
• Bun 1.2.5+

制限付きサポート

• Cloudflare Workers: Agents SDK は Cloudflare Workers で利用できますが、現在はいくつかの制限があります:
  • SDK は現在 nodejs_compat を有効にする必要があります
  • リクエストの最後でトレースを手動で flush する必要があります。詳細は トレーシング ガイド を参照してください。
  • Cloudflare Workers の AsyncLocalStorage サポートが限定的なため、一部のトレースは正確でない場合があります
  • 外向きの WebSocket 接続では、fetch ベースの upgrade（グローバルの WebSocket コンストラクターではない）を使う必要があります。Realtime では、@openai/agents-extensions の Cloudflare トランスポート（CloudflareRealtimeTransportLayer）を使用してください。
• Responses API WebSocket トランスポート:
  • グローバルな WebSocket 実装が必要です。
  • WebSocket 実装は、ハンドシェイク時のカスタムヘッダーをサポートしている必要があります。
  • 多くのブラウザー型 WebSocket API（および一部のエッジランタイム）は、外向きカスタムヘッダーをサポートしていません。そのような環境では、代わりにデフォルトの HTTP Responses トランスポートを使用してください。
  • グローバル WebSocket 実装が見つからない、またはカスタムヘッダーのサポート不足を示すエラーが出る場合、そのランタイムの websocket 実装は Responses WebSocket トランスポートと互換性がありません。
• ブラウザー:
  • コア SDK はブラウザー向けにバンドルできますが、その場合トレーシングはデフォルトで無効です。
• v8 isolates:
  • 適切なブラウザー polyfill を持つ bundler を使えば v8 isolates 向けに SDK をバンドルできるはずですが、トレーシングは動作しません
  • v8 isolates は広範にはテストされていません

デバッグログ

SDK で問題が発生している場合は、デバッグログを有効にすると、何が起きているかについてより多くの情報を得られます。

DEBUG 環境変数を openai-agents:* に設定すると、デバッグログを有効にできます。

DEBUG=openai-agents:*

または、SDK の特定部分にデバッグ対象を絞ることもできます:

• openai-agents:core — SDK のメイン実行ロジック
• openai-agents:openai — OpenAI API 呼び出し
• openai-agents:realtime — リアルタイムエージェントのコンポーネント