Configuration

Configuration (구성)

이 페이지는 애플리케이션 시작 시 한 번 설정하는 SDK 전역 기본값을 다뤄요. 기본 OpenAI 키나 클라이언트, 기본 OpenAI API 형태, 추적(tracing) 내보내기 기본값, 로깅 동작 같은 것들이죠. 이런 기본값은 샌드박스 기반 워크플로에도 적용되지만, 샌드박스 작업 공간·샌드박스 클라이언트·세션 재사용은 별도로 구성해요.

특정 에이전트나 실행(run)만 설정하고 싶다면 여기부터 보세요.

Agents — 일반 Agent에서 지시·도구·출력 타입·handoff·guardrail 설정
Running agents — RunConfig에서 세션·대화 상태 옵션
Sandbox agents — SandboxRunConfig에서 매니페스트·기능·샌드박스 클라이언트별 작업 공간 설정
Models — 모델 선택과 프로바이더 구성
Tracing — 실행별 추적 메타데이터와 커스텀 trace processor

출처: 문서

본문

구성 객체와 딕셔너리

SDK가 정의하는 구성 파라미터는 대개 타이핑된 설정 객체나 같은 필드를 담은 딕셔너리 둘 다 받아요. 이 규칙은 에이전트·실행·모델·세션·샌드박스·음성 구성 경계 전반에 걸쳐 적용되는데, 타입 애너테이션이 딕셔너리를 허용하는 부분이면 어디든 해당돼요. SDK가 정의한 중첩 설정 타입도 딕셔너리를 쓸 수 있어요.

from agents import Agent

agent = Agent(
    name="Assistant",
    model="gpt-5.6-sol",
    model_settings={
        "reasoning": {"effort": "high"},
        "verbosity": "low",
    },
)

SDK는 이런 딕셔너리를 해당 설정 객체로 정규화해요. SDK가 정의한 dataclass 구성 타입에서 알 수 없는 필드를 넣으면 TypeError가 나서, 옵션 이름을 잘못 적은 걸 일찍 잡아주죠. 특정 경계가 딕셔너리를 받는지는 파라미터의 타입 애너테이션이나 API 레퍼런스로 확인해 보세요.

API 키와 클라이언트

기본적으로 SDK는 LLM 요청과 추적에 OPENAI_API_KEY 환경 변수를 사용해요. 키는 SDK가 처음으로 OpenAI 클라이언트를 만들 때(지연 초기화) 해석되므로, 첫 모델 호출 전에 환경 변수를 설정해 두어야 해요. 앱 시작 전에 환경 변수를 설정할 수 없다면 set_default_openai_key() 함수로 키를 설정할 수 있어요.

from agents import set_default_openai_key

set_default_openai_key("sk-...")

또는 사용할 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)

OpenAIProvider에 명시적 클라이언트를 넘기면 그 클라이언트가 자기 연결과 계정 설정을 소유해요. 그러니 OpenAIProvider에 api_key, base_url, websocket_base_url, organization, project를 함께 넘기면 안 돼요. openai_client를 이 인자들과 조합하면 중복 값을 조용히 무시하는 대신 UserError가 발생하니까, 원하는 값은 AsyncOpenAI를 만들 때 설정하세요.

openai_client를 생략하면 OpenAIProvider는 api_key, base_url, websocket_base_url, organization, project가 전부 None일 때만 SDK 전역 기본 클라이언트를 재사용해요. 이 옵션 중 하나라도 넘기면(빈 문자열 포함) 프로바이더가 자기 클라이언트를 만들고, 프로바이더 옵션이 SDK 전역 기본 클라이언트보다 우선해요. 프로바이더가 set_default_openai_client()가 설치한 클라이언트를 상속하길 원한다면 모든 프로바이더 옵션을 None으로 두세요.

OpenAIVoiceModelProvider도 api_key, base_url, organization, project에 대해 같은 소유권·우선순위 규칙을 써요. 명시적 openai_client는 이 네 옵션 중 어떤 것과도 조합할 수 없어요.

openai v3에서 커스텀 HTTP 클라이언트

버전 0.21.0은 openai>=3.0.0,<4를 요구해요. 기본 OpenAI 프로바이더는 HTTPX2를 쓰므로 대부분의 애플리케이션은 HTTP 클라이언트를 직접 구성할 필요가 없어요. 애플리케이션이 AsyncOpenAI에 http_client=를 넘긴다면 커스텀 클라이언트와 그 transport-facing 옵션에 HTTPX2 타입을 쓰세요.

import httpx2
from openai import AsyncOpenAI, DefaultAsyncHttpx2Client

from agents import set_default_openai_client

http_client = DefaultAsyncHttpx2Client(
    timeout=httpx2.Timeout(30.0, connect=5.0),
)
custom_client = AsyncOpenAI(
    api_key="...",
    http_client=http_client,
)
set_default_openai_client(custom_client)

같은 마이그레이션이 커스텀 transport, 인증, 이벤트 훅, mock transport, URL, 요청, 응답, transport 예외 처리에도 적용돼요. 전부 그에 맞는 httpx2 버전을 쓰세요. Agents SDK는 레거시 httpx 객체를 임의로 HTTPX2로 변환하지 않아요. OpenAI Python SDK는 애플리케이션이 httpx를 명시적으로 설치하면 레거시 클라이언트용 임시 호환 경로를 제공하지만, 새 코드와 마이그레이션 코드는 HTTPX2를 쓰는 게 좋아요.

이 OpenAI 클라이언트 경계는 로컬 MCP transport 커스터마이즈와는 별개예요. MCP Python SDK v1은 자체 레거시 httpx 의존성을 쓰고, MCP Python SDK v2는 httpx2를 써요. 자세한 내용은 MCP Python SDK v1과 v2를 참고하세요.

환경 변수 기반 엔드포인트 구성을 선호한다면, 기본 OpenAI 프로바이더는 OPENAI_BASE_URL도 읽어요. Responses websocket transport를 켜면 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로 바꿀 수 있어요.

from agents import set_default_openai_api

set_default_openai_api("chat_completions")

OpenAI 프로바이더 기본값

SDK의 OpenAI 백엔드를 쓰는 프로바이더는 모델 이름 문자열을 모델로 매핑할 때도 SDK 전역 기본값을 읽어요. set_default_openai_responses_transport()로 OpenAI Responses 모델이 기본적으로 websocket transport를 쓰게 만들 수 있어요.

from agents import set_default_openai_responses_transport

set_default_openai_responses_transport("websocket")

이건 기본 OpenAI 프로바이더가 모델 이름을 해석한 결과로 나오는 OpenAI Responses 모델에 영향을 줘요. 프로바이더 수준 설정·연결 재사용·keepalive 옵션·커스텀 websocket 엔드포인트는 Responses WebSocket transport를 참고하세요.

OpenAI 설정이 프로바이더 수준 에이전트 등록 메타데이터를 기대한다면, 시작 시 기본 harness ID를 한 번 설정하세요.

from agents import set_default_openai_harness

set_default_openai_harness("your-harness-id")

전체 등록 객체를 넘길 수도 있어요.

from agents import OpenAIAgentRegistrationConfig, set_default_openai_agent_registration

set_default_openai_agent_registration(
    OpenAIAgentRegistrationConfig(harness_id="your-harness-id")
)

SDK 기본값이 설정되지 않았다면, SDK의 OpenAI 백엔드를 쓰는 프로바이더는 OPENAI_AGENT_HARNESS_ID 환경 변수로 폴백해요. harness ID가 구성되면 SDK는 그 값을 trace 메타데이터에 agent_harness_id로 추가해요. 단, RunConfig.trace_metadata에 그 키가 이미 있으면 추가하지 않아요.

Tracing

추적은 기본적으로 켜져 있어요. 기본적으로 모델 요청과 같은 OpenAI API 키(위 섹션의 환경 변수나 설정한 기본 키)를 사용하고, set_tracing_export_api_key 함수로 추적에 쓸 API 키를 따로 설정할 수 있어요.

from agents import set_tracing_export_api_key

set_tracing_export_api_key("sk-...")

모델 트래픽은 한 키·클라이언트를 쓰는데 추적은 다른 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")

기본 exporter를 쓸 때 trace를 특정 조직·프로젝트에 귀속하고 싶다면 앱 시작 전에 환경 변수를 설정하세요.

export OPENAI_ORG_ID="org_..."
export OPENAI_PROJECT_ID="proj_..."

전역 exporter를 바꾸지 않고 실행별로 추적 API 키를 설정할 수도 있어요.

from agents import Runner, RunConfig

await Runner.run(
    agent,
    input="Hello",
    run_config=RunConfig(tracing={"api_key": "«redacted:sk-…»"}),
)

set_tracing_disabled() 함수로 추적을 완전히 끌 수도 있어요.

from agents import set_tracing_disabled

set_tracing_disabled(True)

추적은 켜둔 채 잠재적으로 민감한 입력/출력을 trace 페이로드에서 제외하고 싶다면 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),
)

코드 없이 앱 시작 전에 환경 변수로 기본값을 바꿀 수도 있어요.

export OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA=0

전체 추적 컨트롤은 tracing 가이드를 참고하세요.

디버그 로깅

SDK는 두 개의 Python 로거(openai.agents, openai.agents.tracing)를 정의하고 기본적으로 핸들러를 붙이지 않아요. 로그는 애플리케이션의 Python logging 구성에 따릅니다.

상세 로깅을 켜려면 enable_verbose_stdout_logging() 함수를 쓰세요.

from agents import enable_verbose_stdout_logging

enable_verbose_stdout_logging()

또는 핸들러·필터·포매터를 추가해 로그를 커스터마이즈할 수 있어요. 자세한 내용은 Python logging 가이드에서 확인할 수 있어요.

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 입력/출력이나 도구 입력/출력을 로그로 남기지 않아요. 이 보호는 아래 설정으로 제어돼요.

OPENAI_AGENTS_DONT_LOG_MODEL_DATA=1
OPENAI_AGENTS_DONT_LOG_TOOL_DATA=1

디버깅을 위해 이 데이터를 일시적으로 포함해야 한다면 앱 시작 전에 두 변수를 0(또는 false)으로 설정하세요.

export OPENAI_AGENTS_DONT_LOG_MODEL_DATA=0
export OPENAI_AGENTS_DONT_LOG_TOOL_DATA=0

이 플래그들은 영향을 받는 실패가 페이로드를 담은 진단 세부 정보를 유지하는지도 제어해요. 예를 들어 도구 데이터 편집이 켜져 있으면, FunctionTool에 잘못된 인자가 들어왔을 때 내부 검증 오류를 연결(chaining)하지 않고 일반 ModelBehaviorError를 발생시켜요. 변수를 0으로 설정하면 로그·예외 메시지·예외 체인·기타 진단 컨텍스트에 원시 모델·도구 데이터가 노출될 수 있으니, 통제된 개발 환경에서만 켜세요.

더 알아보기 (Learn more)

Agents 문서 홈에서 에이전트 설정을 확인하세요.
Tracing·Models·Running agents 가이드도 함께 보면 좋아요.