トラブルシューティング

サポート対象環境

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 transport（CloudflareRealtimeTransportLayer）を使用してください。
• Responses API WebSocket transport:
  • グローバルな WebSocket 実装が必要です
  • WebSocket 実装は、ハンドシェイク時のカスタムヘッダーをサポートしている必要があります
  • 多くのブラウザー系 WebSocket API（および一部の edge runtime）では、外向きのカスタムヘッダーをサポートしていません。そのような環境では、代わりにデフォルトの HTTP Responses transport を使用してください
  • グローバルな WebSocket 実装の欠如やカスタムヘッダーの未サポートに関するエラーが表示される場合、そのランタイムの websocket 実装は Responses WebSocket transport と互換性がありません
• Browsers:
  • コア SDK はブラウザー利用向けにバンドルできますが、その環境ではトレーシングはデフォルトで無効です
• v8 isolates:
  • 適切な browser 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 — リアルタイムエージェントのコンポーネント