SDK 설정

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

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

Runner 및 실행별 옵션은 에이전트 실행을 참조하세요.
에이전트 수준 및 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