문제 해결

지원 환경

OpenAI Agents SDK는 다음 서버 환경을 지원합니다:

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

제한적 지원

• Cloudflare Workers: Agents SDK는 Cloudflare Workers에서 사용할 수 있지만, 현재 몇 가지 제한 사항이 있습니다:
  • 현재 SDK를 사용하려면 nodejs_compat를 활성화해야 합니다
  • 요청이 끝날 때 트레이스를 수동으로 플러시해야 합니다. 자세한 내용은 트레이싱 가이드 보기를 참조하세요.
  • Cloudflare Workers에서는 AsyncLocalStorage 지원이 제한적이므로 일부 트레이스가 정확하지 않을 수 있습니다
  • 아웃바운드 WebSocket 연결에는 전역 WebSocket 생성자가 아닌 fetch 기반 업그레이드를 사용해야 합니다. Realtime에는 @openai/agents-extensions의 Cloudflare 전송 방식(CloudflareRealtimeTransportLayer)을 사용하세요.
• 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 격리 환경은 광범위하게 테스트되지 않았습니다

디버그 로깅

SDK 사용 중 문제가 발생하면 디버그 로깅을 활성화하여 현재 상황에 대한 자세한 정보를 확인할 수 있습니다.

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

DEBUG=openai-agents:*

모델 및 도구 데이터는 기본적으로 가려집니다. 해당 세부 정보가 필요한 경우 로그의 민감한 데이터를 참조하고, 로그가 안전하게 처리되는 경우에만 데이터 기록을 활성화하세요.

또는 디버깅 범위를 SDK의 특정 부분으로 제한할 수 있습니다:

• openai-agents:core — SDK의 주요 실행 로직
• openai-agents:openai — OpenAI API 호출
• openai-agents:realtime — 음성 에이전트 구성 요소