Troubleshooting

Supported environments

The OpenAI Agents SDK is supported on the following server environments:

Cloudflare Workers: The Agents SDK can be used in Cloudflare Workers, but currently comes with some limitations:
- The SDK current requires nodejs_compat to be enabled
- Traces need to be manually flushed at the end of the request. See the tracing guide for more details.
- Due to Cloudflare Workers’ limited support for AsyncLocalStorage some traces might not be accurate
- Outbound WebSocket connections must use a fetch-based upgrade (not the global WebSocket constructor). For Realtime, use the Cloudflare transport in @openai/agents-extensions (CloudflareRealtimeTransportLayer).
Responses API WebSocket transport:
- Requires a global WebSocket implementation.
- The WebSocket implementation must support custom headers for the handshake.
- Many browser-style WebSocket APIs (and some edge runtimes) do not support custom outbound headers. In those environments, use the default HTTP Responses transport instead.
- If you see errors mentioning a missing global WebSocket implementation or lack of custom-header support, the runtime websocket implementation is not compatible with the Responses WebSocket transport.
Browsers:
- Tracing is currently not supported in browsers
v8 isolates:
- While you should be able to bundle the SDK for v8 isolates if you use a bundler with the right browser polyfills, tracing will not work
- v8 isolates have not been extensively tested

If you are running into problems with the SDK, you can enable debug logging to get more information about what is happening.

Enable debug logging by setting the DEBUG environment variable to openai-agents:*.

DEBUG=openai-agents:*

Alternatively, you can scope the debugging to specific parts of the SDK: