トラブルシューティング

サポート対象環境

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

Node.js 22+
Deno 2.35+
Bun 1.2.5+

制限付きサポート

Cloudflare Workers：Agents SDK は Cloudflare Workers で使用できますが、現時点ではいくつかの制限があります。
- 現在、SDK では nodejs_compat を有効にする必要があります
- リクエストの終了時に、トレースを手動でフラッシュする必要があります。詳細については、トレーシングガイドを参照してください。
- Cloudflare Workers では AsyncLocalStorage のサポートが限定的なため、一部のトレースが正確でない可能性があります
- 外向きの WebSocket 接続では、グローバルな WebSocket コンストラクターではなく、fetch ベースのアップグレードを使用する必要があります。Realtime では、@openai/agents-extensions の Cloudflare トランスポート（CloudflareRealtimeTransportLayer）を使用してください。
Responses API WebSocket トランスポート：
- グローバルな WebSocket 実装が必要です。
- WebSocket 実装は、ハンドシェイク用のカスタムヘッダーをサポートしている必要があります。
- 多くのブラウザースタイルの WebSocket API（および一部のエッジランタイム）は、外向きのカスタムヘッダーをサポートしていません。そのような環境では、代わりにデフォルトの HTTP Responses トランスポートを使用してください。
- グローバルな WebSocket 実装が見つからない、またはカスタムヘッダーがサポートされていないことを示すエラーが表示された場合、そのランタイムの WebSocket 実装は Responses WebSocket トランスポートと互換性がありません。
ブラウザー：
- コア SDK はブラウザー向けにバンドルできますが、ブラウザーではデフォルトでトレーシングが無効になっています。
v8 isolates：
- 適切なブラウザーポリフィルを備えたバンドラーを使用すれば、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 — リアルタイムエージェントのコンポーネント用