トラブルシューティング
サポート対象環境
Section titled “サポート対象環境”OpenAI Agents SDK は、次のサーバー環境でサポートされています。
- Node.js 22+
- Deno 2.35+
- Bun 1.2.5+
制限付きサポート
Section titled “制限付きサポート”- Cloudflare Workers : Agents SDK は Cloudflare Workers で使用できますが、現在はいくつかの制限があります。
- 現在、SDK を使用するには
nodejs_compatを有効にする必要があります - リクエストの終了時にトレースを手動でフラッシュする必要があります。詳細はトレーシングを参照してください。
- Cloudflare Workers の
AsyncLocalStorageサポートは限定的なため、一部のトレースが不正確になる可能性があります - アウトバウンドの WebSocket 接続では、fetch ベースのアップグレードを使用する必要があります(グローバルの
WebSocketコンストラクターは使用できません)。Realtime では、@openai/agents-extensionsの Cloudflare トランスポート(CloudflareRealtimeTransportLayer)を使用してください。
- 現在、SDK を使用するには
- Responses API WebSocket トランスポート :
- グローバルの
WebSocket実装が必要です。 WebSocket実装は、ハンドシェイクでのカスタムヘッダーをサポートしている必要があります。- ブラウザースタイルの WebSocket API の多く(および一部のエッジランタイム)は、カスタムの送信ヘッダーをサポートしていません。これらの環境では、代わりにデフォルトの HTTP Responses トランスポートを使用してください。
- グローバルの
WebSocket実装がない、またはカスタムヘッダーがサポートされていないことを示すエラーが表示される場合、そのランタイムの WebSocket 実装は Responses WebSocket トランスポートと互換性がありません。
- グローバルの
- ブラウザー :
- コア SDK はブラウザー用にバンドルできますが、ブラウザーではトレーシングがデフォルトで無効になっています。
- React Native :
@openai/agents-coreと@openai/agents-realtimeは、ポータブルな shim のために React Native 向けのパッケージ条件を提供していますが、組み込みのOpenAIRealtimeWebRTCは引き続きブラウザー専用です。- Realtime アプリでは、
react-native-webrtcなどのネイティブ WebRTC 実装を基盤とする、アプリ独自のトランスポートを用意する必要があります。また、権限、音声ルーティング、トランスポートのライフサイクルは、引き続きアプリ側の責任で管理する必要があります。 - Expo Go はネイティブ WebRTC モジュールを読み込めません。Expo 開発ビルドまたはネイティブの React Native プロジェクトを使用してください。
examples/realtime-react-nativeのコード例を参照してください。
- v8 アイソレート :
- 適切なブラウザー向けポリフィルを備えたバンドラーを使用すれば、v8 アイソレート向けに SDK をバンドルできるはずですが、トレーシングは動作しません
- v8 アイソレートでのテストは十分に行われていません
デバッグログ
Section titled “デバッグログ”SDK で問題が発生した場合は、デバッグログを有効にして、何が起きているかについて詳しい情報を取得できます。
環境変数 DEBUG を openai-agents:* に設定すると、デバッグログが有効になります。
DEBUG=openai-agents:*モデルとツールのデータは、デフォルトではマスキングされたままです。これらの詳細が必要な場合は、ログ内の機密データを参照し、ログが安全に扱われる環境でのみ明示的に有効にしてください。
また、デバッグの対象を SDK の特定の部分に限定することもできます。
openai-agents:core— SDK のメインの実行ロジックopenai-agents:openai— OpenAI API の呼び出しopenai-agents:realtime— 音声エージェントのコンポーネント