SDK 설정
이 페이지에서는 기본 OpenAI 클라이언트, 전송 방식, 트레이싱 내보내기 키, 디버그 로깅 동작처럼 일반적으로 앱 시작 시 한 번 설정하는 SDK 전역 기본값을 다룹니다. 이러한 설정은 기본적으로 프로세스 전체에 적용되므로, 에이전트별 또는 실행별 조정보다는 전역 설정에 적합합니다.
특정 Agent, Runner 또는 run() 호출을 설정하려면 다음 문서를 참조하세요.
- 에이전트 실행에서
Runner및 실행별 옵션을 확인할 수 있습니다. - 모델에서 에이전트 수준 및 러너 수준의 모델 설정을 확인할 수 있습니다.
- 트레이싱에서 실행별 트레이싱 설정과 내보내기 도구의 동작을 확인할 수 있습니다.
OpenAI 클라이언트 및 전송 방식
섹션 제목: “OpenAI 클라이언트 및 전송 방식”API 키 및 클라이언트
섹션 제목: “API 키 및 클라이언트”기본적으로 SDK는 OpenAI 클라이언트를 생성해야 하는 시점에 OPENAI_API_KEY 값을 조회합니다. 환경 변수를 설정할 수 없다면 setDefaultOpenAIKey() 함수를 직접 호출하세요.
import { setDefaultOpenAIKey } from '@openai/agents';
setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...자체 OpenAI 클라이언트 인스턴스를 전달할 수도 있습니다. 별도로 전달하지 않으면 SDK가 기본 키를 사용해 클라이언트를 자동으로 생성합니다.
import { OpenAI } from 'openai';import { setDefaultOpenAIClient } from '@openai/agents';
const customClient = new OpenAI({ baseURL: '...', apiKey: '...' });setDefaultOpenAIClient(customClient);API 선택
섹션 제목: “API 선택”마지막으로 Responses API와 Chat Completions API 간에 전환할 수 있습니다.
import { setOpenAIAPI } from '@openai/agents';
setOpenAIAPI('chat_completions');Responses 전송 방식
섹션 제목: “Responses 전송 방식”Responses API를 사용하는 경우 OpenAI 공급자의 전송 방식도 선택할 수 있습니다. 기본값은 HTTP입니다.
import { setOpenAIAPI, setOpenAIResponsesTransport } from '@openai/agents';
setOpenAIAPI('responses');setOpenAIResponsesTransport('websocket');WebSocket 전송 방식을 활성화하려면 setOpenAIResponsesTransport('websocket') 함수를 사용하고, 다시 전환하려면 setOpenAIResponsesTransport('http') 함수를 사용하세요. WebSocket 트래픽을 프록시나 게이트웨이를 통해 라우팅한다면 OPENAI_WEBSOCKET_BASE_URL 환경 변수를 설정하거나 OpenAIProvider 객체의 websocketBaseURL 값을 설정하세요.
이 프로세스 전역 기본값은 이후 기본 OpenAI 공급자를 통해 결정되는 모델에만 영향을 줍니다. 구체적인 Model 인스턴스나 사용자 정의 modelProvider 객체를 전달한다면 해당 객체에서 전송 방식을 설정하세요. 모델 문서를 참조하세요.
관측 가능성 및 디버깅
섹션 제목: “관측 가능성 및 디버깅”트레이싱
섹션 제목: “트레이싱”트레이싱은 지원되는 서버 런타임에서 기본적으로 활성화됩니다. 브라우저와 NODE_ENV=test 환경에서는 기본적으로 비활성화됩니다.
기본적으로 트레이스 내보내기에는 위 섹션에서 설명한 것과 동일한 OpenAI 키가 사용됩니다.
setTracingExportApiKey() 함수를 통해 별도의 키를 설정할 수 있습니다.
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');트레이싱을 완전히 비활성화할 수도 있습니다.
import { setTracingDisabled } from '@openai/agents';
setTracingDisabled(true);트레이싱 기능에 대해 자세히 알아보려면 트레이싱 문서를 참조하세요.
디버그 로깅
섹션 제목: “디버그 로깅”SDK는 디버그 로깅에 debug 패키지를 사용합니다. 상세 로그를 보려면 DEBUG 환경 변수를 openai-agents* 값으로 설정하세요.
export DEBUG=openai-agents*세션 영속화 작업을 기록하려면 OPENAI_AGENTS__DEBUG_SAVE_SESSION=1 환경 변수를 설정하세요.
@openai/agents 패키지의 getLogger(namespace) 함수를 사용하면 자체 모듈용으로 네임스페이스가 지정된 로거를 얻을 수 있습니다.
import { getLogger } from '@openai/agents';
const logger = getLogger('my-app');logger.debug('something happened');로그의 민감한 데이터
섹션 제목: “로그의 민감한 데이터”관련 오류 객체와 세부 정보를 포함한 모델 및 도구 데이터는 기본적으로 로그에 포함되지 않습니다. 디버깅 중에 이러한 세부 정보가 필요하다면 프로세스의 민감한 데이터 로깅을 명시적으로 활성화할 수 있습니다.
import { setSensitiveDataLoggingEnabled } from '@openai/agents';
setSensitiveDataLoggingEnabled(true);로그를 안전하게 처리하는 환경에서만 이 기능을 활성화하세요. 프로그래밍 방식의 설정은 모델 및 도구 데이터를 모두 제어하며, 아래 환경 변수보다 우선합니다. 민감한 데이터 로깅을 다시 비활성화하려면 setSensitiveDataLoggingEnabled(false) 함수를 호출하세요.
환경 변수를 사용해 모델 및 도구 데이터 로깅을 각각 활성화할 수도 있습니다. 해당하는 OPENAI_AGENTS_DONT_LOG_* 변수를 0 또는 false 값으로 설정하세요.
export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0어느 변수든 1 또는 true 값으로 설정하면 해당 데이터와 관련 오류 세부 정보가 계속 가려집니다. 값이 설정되지 않았거나 인식할 수 없는 값인 경우에도 안전한 기본값이 사용되어 민감한 데이터가 로그에 포함되지 않습니다.