문제 해결

지원 환경

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 전송:
  • 글로벌 WebSocket 구현이 필요
  • 핸드셰이크를 위한 커스텀 헤더를 지원하는 WebSocket 구현이 필요
  • 브라우저 스타일의 많은 WebSocket API(및 일부 엣지 런타임)는 커스텀 아웃바운드 헤더를 지원하지 않음. 해당 환경에서는 기본 HTTP Responses 전송을 사용
  • 글로벌 WebSocket 구현 누락 또는 커스텀 헤더 미지원과 관련된 오류가 나타나면, 해당 런타임의 WebSocket 구현은 Responses WebSocket 전송과 호환되지 않음
• 브라우저:
  • 브라우저에서는 현재 트레이싱이 지원되지 않음
• v8 isolates:
  • 적절한 브라우저 폴리필을 갖춘 번들러를 사용하면 SDK를 v8 isolates용으로 번들링할 수 있으나, 트레이싱은 동작하지 않음
  • v8 isolates는 광범위하게 테스트되지 않음

디버그 로깅

SDK 사용 중 문제가 발생하는 경우, 디버그 로깅을 활성화하여 동작에 대한 더 많은 정보를 확인할 수 있습니다.

DEBUG 환경 변수를 openai-agents:*로 설정하여 디버그 로깅을 활성화하세요.

DEBUG=openai-agents:*

또는 SDK의 특정 부분에 범위를 한정하여 디버깅할 수 있습니다:

• openai-agents:core — SDK의 주요 실행 로직
• openai-agents:openai — OpenAI API 호출
• openai-agents:realtime — Realtime Agents 구성 요소