SDK 설정

이 페이지에서는 앱 시작 시 보통 한 번만 설정하는 SDK 전역 기본값을 다룹니다. 예를 들어 기본 OpenAI 클라이언트, 전송 방식, 트레이싱 export 키, 디버그 로깅 동작이 이에 해당합니다. 이 설정들은 기본적으로 프로세스 전역에 적용되므로, 에이전트별 또는 실행별 세부 조정보다는 공통 설정에 적합한 위치입니다.

대신 특정 Agent, Runner, 또는 run() 호출을 설정해야 한다면 다음을 참고하세요.

Runner 및 실행별 옵션은 에이전트 실행을 참고하세요.
에이전트 수준 및 러너 수준 모델 설정은 모델을 참고하세요.
실행별 트레이싱 설정 및 exporter 동작은 트레이싱을 참고하세요.

OpenAI 클라이언트 및 전송 방식

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 선택

마지막으로 Responses API와 Chat Completions API 사이를 전환할 수 있습니다.

import { setOpenAIAPI } from '@openai/agents';

setOpenAIAPI('chat_completions');

Responses 전송 방식

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

import { setOpenAIAPI, setOpenAIResponsesTransport } from '@openai/agents';

setOpenAIAPI('responses');
setOpenAIResponsesTransport('websocket');

WebSocket 전송을 활성화하려면 setOpenAIResponsesTransport('websocket')를 사용하고, 다시 전환하려면 setOpenAIResponsesTransport('http')를 사용하세요. websocket 트래픽을 프록시 또는 게이트웨이를 통해 라우팅한다면 OPENAI_WEBSOCKET_BASE_URL을 설정하세요(또는 OpenAIProvider에서 websocketBaseURL을 설정하세요).

이 프로세스 전역 기본값은 이후 기본 OpenAI provider를 통해 확인되는 모델에만 영향을 줍니다. 구체적인 Model 인스턴스 또는 커스텀 modelProvider를 전달하는 경우에는 해당 위치에서 전송 방식을 설정하세요. 모델 가이드를 참고하세요.

관측 가능성 및 디버깅

트레이싱

트레이싱은 지원되는 서버 런타임에서 기본적으로 활성화됩니다. 브라우저에서는 기본적으로 비활성화되며 NODE_ENV=test일 때도 비활성화됩니다.

기본적으로 trace export는 위 섹션과 동일한 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');

로그의 민감한 데이터

일부 로그에는 사용자 데이터가 포함될 수 있습니다. 아래 환경 변수를 설정해 비활성화하세요.

LLM 입력과 출력을 로깅하지 않으려면 다음을 설정하세요.

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1

도구 입력과 출력을 로깅하지 않으려면 다음을 설정하세요.

export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1