콘텐츠로 이동

문제 해결

지원 환경

섹션 제목: “지원 환경”

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 연결은 fetch 기반 업그레이드를 사용해야 합니다(전역 WebSocket 생성자가 아님). Realtime의 경우 @openai/agents-extensions의 Cloudflare 전송 방식(CloudflareRealtimeTransportLayer)을 사용하세요.
  • Responses API WebSocket 전송 방식:
    • 전역 WebSocket 구현이 필요합니다.
    • WebSocket 구현은 핸드셰이크에 대한 사용자 지정 헤더를 지원해야 합니다.
    • 많은 브라우저 스타일 WebSocket API(및 일부 에지 런타임)는 사용자 지정 아웃바운드 헤더를 지원하지 않습니다. 이러한 환경에서는 대신 기본 HTTP Responses 전송 방식을 사용하세요.
    • 전역 WebSocket 구현이 없거나 사용자 지정 헤더 지원이 부족하다는 오류가 표시되면, 런타임 websocket 구현이 Responses WebSocket 전송 방식과 호환되지 않는 것입니다.
  • 브라우저:
    • 코어 SDK는 브라우저 사용을 위해 번들링할 수 있지만, 그곳에서는 트레이싱이 기본적으로 비활성화됩니다.
  • v8 isolates:
    • 적절한 브라우저 polyfill을 갖춘 번들러를 사용하면 SDK를 v8 isolates용으로 번들링할 수는 있지만, 트레이싱은 작동하지 않습니다.
    • v8 isolates는 광범위하게 테스트되지 않았습니다.

디버그 로깅

섹션 제목: “디버그 로깅”

SDK에 문제가 발생하면 디버그 로깅을 활성화하여 현재 상황에 대한 더 많은 정보를 얻을 수 있습니다.

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

Terminal window
DEBUG=openai-agents:*

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

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