문제 해결

지원 환경

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를 브라우저용으로 번들링할 수 있지만, 브라우저에서는 트레이싱이 기본적으로 비활성화됩니다.
• v8 isolates:
  • 적절한 브라우저 폴리필이 포함된 번들러를 사용하면 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 — 실시간 에이전트 구성 요소