문제 해결

지원 환경

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 기반 업그레이드(전역 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 — 실시간 에이전트 구성 요소용