콘텐츠로 이동

SDK 설정

이 페이지에서는 기본 OpenAI 클라이언트, 전송 방식, 트레이싱 내보내기 키, 디버그 로깅 동작처럼 일반적으로 앱 시작 시 한 번 설정하는 SDK 전역 기본값을 다룹니다. 이러한 설정은 기본적으로 프로세스 전체에 적용되므로, 에이전트별 또는 실행별 조정보다는 전역 설정에 적합합니다.

특정 Agent, Runner 또는 run() 호출을 설정하려면 다음 문서를 참조하세요.

  • 에이전트 실행에서 Runner 및 실행별 옵션을 확인할 수 있습니다.
  • 모델에서 에이전트 수준 및 러너 수준의 모델 설정을 확인할 수 있습니다.
  • 트레이싱에서 실행별 트레이싱 설정과 내보내기 도구의 동작을 확인할 수 있습니다.

기본적으로 SDK는 OpenAI 클라이언트를 생성해야 하는 시점에 OPENAI_API_KEY 값을 조회합니다. 환경 변수를 설정할 수 없다면 setDefaultOpenAIKey() 함수를 직접 호출하세요.

기본 OpenAI 키 설정
import { setDefaultOpenAIKey } from '@openai/agents';
setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

자체 OpenAI 클라이언트 인스턴스를 전달할 수도 있습니다. 별도로 전달하지 않으면 SDK가 기본 키를 사용해 클라이언트를 자동으로 생성합니다.

기본 OpenAI 클라이언트 설정
import { OpenAI } from 'openai';
import { setDefaultOpenAIClient } from '@openai/agents';
const customClient = new OpenAI({ baseURL: '...', apiKey: '...' });
setDefaultOpenAIClient(customClient);

마지막으로 Responses API와 Chat Completions API 간에 전환할 수 있습니다.

OpenAI API 설정
import { setOpenAIAPI } from '@openai/agents';
setOpenAIAPI('chat_completions');

Responses API를 사용하는 경우 OpenAI 공급자의 전송 방식도 선택할 수 있습니다. 기본값은 HTTP입니다.

Responses 전송 방식 설정
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() 함수를 통해 별도의 키를 설정할 수 있습니다.

트레이싱 내보내기 API 키 설정
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=0
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0

어느 변수든 1 또는 true 값으로 설정하면 해당 데이터와 관련 오류 세부 정보가 계속 가려집니다. 값이 설정되지 않았거나 인식할 수 없는 값인 경우에도 안전한 기본값이 사용되어 민감한 데이터가 로그에 포함되지 않습니다.