구성
이 페이지에서는 기본 OpenAI 키 또는 클라이언트, 기본 OpenAI API 형태, 트레이싱 내보내기 기본값, 로깅 동작처럼 보통 애플리케이션 시작 시 한 번 설정하는 SDK 전역 기본값을 다룹니다
이러한 기본값은 샌드박스 기반 워크플로에도 계속 적용되지만, 샌드박스 워크스페이스, 샌드박스 클라이언트, 세션 재사용은 별도로 구성합니다
대신 특정 에이전트 또는 실행을 구성해야 한다면, 다음부터 시작하세요:
- 일반
Agent의 instructions, tools, 출력 타입, 핸드오프, 가드레일은 Agents RunConfig, 세션, 대화 상태 옵션은 에이전트 실행SandboxRunConfig, 매니페스트, 기능, 샌드박스 클라이언트 전용 워크스페이스 설정은 샌드박스 에이전트- 모델 선택 및 프로바이더 구성은 모델
- 실행별 트레이싱 메타데이터와 사용자 지정 트레이스 프로세서는 트레이싱
API 키와 클라이언트
기본적으로 SDK는 LLM 요청과 트레이싱에 OPENAI_API_KEY 환경 변수를 사용합니다. 이 키는 SDK가 처음 OpenAI 클라이언트를 생성할 때(지연 초기화) 확인되므로, 첫 모델 호출 전에 환경 변수를 설정하세요. 앱 시작 전에 해당 환경 변수를 설정할 수 없다면 set_default_openai_key() 함수를 사용해 키를 설정할 수 있습니다.
또는 사용할 OpenAI 클라이언트를 구성할 수도 있습니다. 기본적으로 SDK는 환경 변수의 API 키 또는 위에서 설정한 기본 키를 사용해 AsyncOpenAI 인스턴스를 생성합니다. set_default_openai_client() 함수를 사용해 이를 변경할 수 있습니다.
from openai import AsyncOpenAI
from agents import set_default_openai_client
custom_client = AsyncOpenAI(base_url="...", api_key="...")
set_default_openai_client(custom_client)
환경 기반 엔드포인트 구성을 선호한다면, 기본 OpenAI 프로바이더는 OPENAI_BASE_URL도 읽습니다. Responses websocket 전송을 활성화하면 websocket /responses 엔드포인트에 OPENAI_WEBSOCKET_BASE_URL도 읽습니다.
export OPENAI_BASE_URL="https://your-openai-compatible-endpoint.example/v1"
export OPENAI_WEBSOCKET_BASE_URL="wss://your-openai-compatible-endpoint.example/v1"
마지막으로, 사용되는 OpenAI API를 사용자 지정할 수도 있습니다. 기본적으로는 OpenAI Responses API를 사용합니다. set_default_openai_api() 함수를 사용하면 이를 재정의해 Chat Completions API를 사용할 수 있습니다.
트레이싱
트레이싱은 기본적으로 활성화되어 있습니다. 기본적으로 위 섹션의 모델 요청과 동일한 OpenAI API 키(즉, 환경 변수 또는 설정한 기본 키)를 사용합니다. set_tracing_export_api_key 함수를 사용해 트레이싱에 사용할 API 키를 별도로 설정할 수 있습니다.
모델 트래픽은 하나의 키 또는 클라이언트를 사용하지만 트레이싱은 다른 OpenAI 키를 사용해야 한다면, 기본 키 또는 클라이언트를 설정할 때 use_for_tracing=False를 전달한 다음 트레이싱을 별도로 구성하세요. 사용자 지정 클라이언트를 사용하지 않는 경우 set_default_openai_key()에도 같은 패턴을 적용할 수 있습니다.
from openai import AsyncOpenAI
from agents import (
set_default_openai_client,
set_tracing_export_api_key,
)
custom_client = AsyncOpenAI(base_url="https://your-openai-compatible-endpoint.example/v1", api_key="provider-key")
set_default_openai_client(custom_client, use_for_tracing=False)
set_tracing_export_api_key("sk-tracing")
기본 내보내기를 사용할 때 트레이스를 특정 조직 또는 프로젝트에 귀속해야 한다면, 앱 시작 전에 다음 환경 변수를 설정하세요:
전역 내보내기를 변경하지 않고 실행별로 트레이싱 API 키를 설정할 수도 있습니다.
from agents import Runner, RunConfig
await Runner.run(
agent,
input="Hello",
run_config=RunConfig(tracing={"api_key": "sk-tracing-123"}),
)
set_tracing_disabled() 함수를 사용해 트레이싱을 완전히 비활성화할 수도 있습니다.
트레이싱은 활성화한 채로 유지하되 트레이스 페이로드에서 잠재적으로 민감한 입력/출력을 제외하려면 RunConfig.trace_include_sensitive_data를 False로 설정하세요:
from agents import Runner, RunConfig
await Runner.run(
agent,
input="Hello",
run_config=RunConfig(trace_include_sensitive_data=False),
)
코드 없이 기본값을 변경하려면 앱 시작 전에 이 환경 변수를 설정할 수도 있습니다:
전체 트레이싱 제어는 트레이싱 가이드를 참고하세요.
디버그 로깅
SDK는 두 개의 Python 로거(openai.agents 및 openai.agents.tracing)를 정의하며 기본적으로 핸들러를 연결하지 않습니다. 로그는 애플리케이션의 Python 로깅 구성 설정을 따릅니다.
상세 로깅을 활성화하려면 enable_verbose_stdout_logging() 함수를 사용하세요.
또는 핸들러, 필터, 포매터 등을 추가해 로그를 사용자 지정할 수 있습니다. 자세한 내용은 Python 로깅 가이드를 참고하세요.
import logging
logger = logging.getLogger("openai.agents") # or openai.agents.tracing for the Tracing logger
# To make all logs show up
logger.setLevel(logging.DEBUG)
# To make info and above show up
logger.setLevel(logging.INFO)
# To make warning and above show up
logger.setLevel(logging.WARNING)
# etc
# You can customize this as needed, but this will output to `stderr` by default
logger.addHandler(logging.StreamHandler())
로그의 민감한 데이터
일부 로그에는 민감한 데이터(예: 사용자 데이터)가 포함될 수 있습니다.
기본적으로 SDK는 LLM 입력/출력이나 도구 입력/출력을 로깅하지 않습니다. 이러한 보호는 다음으로 제어됩니다:
디버깅을 위해 이 데이터를 일시적으로 포함해야 한다면 앱 시작 전에 변수 중 하나를 0(또는 false)으로 설정하세요: