문제 해결
지원 환경
섹션 제목: “지원 환경”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)을 사용하세요.
- 현재 SDK를 사용하려면
- 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 설정의 로그 내 민감한 데이터 섹션을 참조하고, 로그가 안전하게 처리되는 환경에서만 해당 데이터 로깅을 활성화하세요.
또는 SDK의 특정 부분으로 디버깅 범위를 한정할 수 있습니다:
openai-agents:core— SDK의 주요 실행 로직openai-agents:openai— OpenAI API 호출openai-agents:realtime— 음성 에이전트 구성 요소