문제 해결

지원 환경

OpenAI Agents SDK는 다음 서버 환경에서 지원됩니다:

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

제한적 지원

• Cloudflare Workers: Agents SDK를 Cloudflare Workers에서 사용할 수 있지만, 현재 몇 가지 제한이 있습니다:
  • SDK는 현재 nodejs_compat 활성화를 요구합니다
  • 요청이 끝날 때 트레이스를 수동으로 flush해야 합니다. 자세한 내용은 See the tracing guide를 참고하세요.
  • Cloudflare Workers의 AsyncLocalStorage 지원이 제한적이므로 일부 트레이스가 정확하지 않을 수 있습니다
  • 아웃바운드 WebSocket 연결은 fetch 기반 업그레이드를 사용해야 합니다(전역 WebSocket 생성자 아님). Realtime의 경우 @openai/agents-extensions의 Cloudflare 전송(CloudflareRealtimeTransportLayer)을 사용하세요
• Responses API WebSocket transport:
  • 전역 WebSocket 구현이 필요합니다
  • WebSocket 구현은 핸드셰이크용 사용자 지정 헤더를 지원해야 합니다
  • 많은 브라우저 스타일 WebSocket API(및 일부 엣지 런타임)는 사용자 지정 아웃바운드 헤더를 지원하지 않습니다. 이러한 환경에서는 대신 기본 HTTP Responses transport를 사용하세요
  • 전역 WebSocket 구현 누락 또는 사용자 지정 헤더 지원 부족 관련 오류가 발생하면, 해당 런타임 websocket 구현은 Responses WebSocket transport와 호환되지 않습니다
• 브라우저:
  • 코어 SDK는 브라우저에서 사용할 수 있도록 번들링할 수 있지만, 해당 환경에서는 기본적으로 트레이싱이 비활성화됩니다
• v8 isolates:
  • 적절한 브라우저 polyfill이 포함된 번들러를 사용하면 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 — 실시간 에이전트 구성 요소