SDK 설정

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

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

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

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 프로바이더 전송 방식도 선택할 수 있습니다. 기본값은 HTTP입니다.

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

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

setOpenAIResponsesTransport('websocket')를 사용하면 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');

로그의 민감한 데이터

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

LLM 입력 및 출력을 기록하지 않으려면 다음을 설정하세요.

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1

도구 입력 및 출력을 기록하지 않으려면 다음을 설정하세요.

export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1