모델

Agents SDK는 두 가지 방식으로 OpenAI 모델을 바로 사용할 수 있도록 지원합니다:

권장: 새로운 Responses API를 사용하는 OpenAIResponsesModel
Chat Completions API를 사용하는 OpenAIChatCompletionsModel

OpenAI 모델

Agent를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 호환성과 낮은 지연 시간을 위해 gpt-4.1입니다. 접근 권한이 있다면 더 높은 품질을 위해 에이전트를 gpt-5.2로 설정하고 model_settings는 명시적으로 유지할 것을 권장합니다.

gpt-5.2와 같은 다른 모델로 전환하려면 다음 섹션의 단계를 따르세요.

기본 OpenAI 모델

사용자 지정 모델을 설정하지 않은 모든 에이전트에 대해 일관되게 특정 모델을 사용하려면, 에이전트를 실행하기 전에 OPENAI_DEFAULT_MODEL 환경 변수를 설정하세요.

export OPENAI_DEFAULT_MODEL=gpt-5
python3 my_awesome_agent.py

GPT-5 모델

이 방식으로 GPT-5의 추론 모델들(gpt-5, gpt-5-mini, gpt-5-nano)을 사용할 때, SDK는 기본적으로 합리적인 ModelSettings를 적용합니다. 구체적으로 reasoning.effort와 verbosity를 모두 "low"로 설정합니다. 이러한 설정을 직접 구성하려면 agents.models.get_default_model_settings("gpt-5")를 호출하세요.

더 낮은 지연 시간이나 특정 요구 사항이 있는 경우, 다른 모델과 설정을 선택할 수 있습니다. 기본 모델의 추론 강도를 조정하려면 직접 ModelSettings를 전달하세요:

from openai.types.shared import Reasoning
from agents import Agent, ModelSettings

my_agent = Agent(
    name="My Agent",
    instructions="You're a helpful agent.",
    model_settings=ModelSettings(reasoning=Reasoning(effort="minimal"), verbosity="low")
    # If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only model_settings works.
    # It's also fine to pass a GPT-5 model name explicitly:
    # model="gpt-5",
)

특히 지연 시간을 낮추려면 gpt-5-mini 또는 gpt-5-nano 모델을 reasoning.effort="minimal"과 함께 사용하면 기본 설정보다 더 빠르게 응답하는 경우가 많습니다. 다만 Responses API의 일부 내장 도구(예: 파일 검색과 이미지 생성)는 "minimal" 추론 강도를 지원하지 않으므로, 이 Agents SDK는 기본값을 "low"로 사용합니다.

GPT-5 이외의 모델

사용자 지정 model_settings 없이 GPT-5가 아닌 모델 이름을 전달하면, SDK는 어떤 모델에도 호환되는 일반 ModelSettings로 되돌립니다.

비 OpenAI 모델

대부분의 다른 비 OpenAI 모델은 LiteLLM integration을 통해 사용할 수 있습니다. 먼저 litellm 의존성 그룹을 설치하세요:

pip install "openai-agents[litellm]"

그런 다음 litellm/ 프리픽스를 사용해 supported models 중 아무거나 사용할 수 있습니다:

claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...)
gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...)

비 OpenAI 모델 사용의 기타 방법

다른 LLM 제공자를 통합하는 방법은 추가로 3가지가 있습니다(예시는 여기 참조):

set_default_openai_client는 전역적으로 AsyncOpenAI 인스턴스를 LLM 클라이언트로 사용하고 싶을 때 유용합니다. 이는 LLM 제공자가 OpenAI 호환 API 엔드포인트를 제공하고 base_url과 api_key를 설정할 수 있는 경우를 위한 것입니다. 설정 가능한 예시는 examples/model_providers/custom_example_global.py를 참조하세요.
ModelProvider는 Runner.run 수준에서 동작합니다. 이를 통해 "이 실행의 모든 에이전트에 사용자 지정 모델 제공자를 사용"하도록 지정할 수 있습니다. 설정 가능한 예시는 examples/model_providers/custom_example_provider.py를 참조하세요.
Agent.model을 사용하면 특정 Agent 인스턴스에서 모델을 지정할 수 있습니다. 이를 통해 에이전트마다 서로 다른 제공자를 혼합해 사용할 수 있습니다. 설정 가능한 예시는 examples/model_providers/custom_example_agent.py를 참조하세요. 대부분의 사용 가능한 모델을 간편히 사용하는 방법은 LiteLLM integration을 통한 것입니다.

platform.openai.com의 API 키가 없는 경우, set_tracing_disabled()를 통해 트레이싱을 비활성화하거나, 다른 트레이싱 프로세서를 설정하는 것을 권장합니다.

Note

이 예시들에서는 대부분의 LLM 제공자가 아직 Responses API를 지원하지 않기 때문에 Chat Completions API/모델을 사용합니다. LLM 제공자가 Responses API를 지원한다면 Responses 사용을 권장합니다.

모델 혼합 사용

단일 워크플로 내에서 에이전트마다 서로 다른 모델을 사용하고자 할 수 있습니다. 예를 들어, 분류(트리아지)에는 더 작고 빠른 모델을 사용하고, 복잡한 작업에는 더 크고 강력한 모델을 사용할 수 있습니다. Agent를 구성할 때 다음 중 한 가지 방식으로 특정 모델을 선택할 수 있습니다:

모델 이름을 전달
임의의 모델 이름 + 해당 이름을 모델 인스턴스로 매핑할 수 있는 ModelProvider를 전달
Model 구현을 직접 제공

Note

SDK는 OpenAIResponsesModel과 OpenAIChatCompletionsModel 두 형태를 모두 지원하지만, 두 형태가 지원하는 기능과 도구가 다르므로 각 워크플로에서는 단일 모델 형태를 사용할 것을 권장합니다. 워크플로가 모델 형태의 혼합을 필요로 하는 경우, 사용하는 모든 기능이 양쪽에서 모두 제공되는지 확인하세요.

from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
import asyncio

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You only speak Spanish.",
    model="gpt-5-mini", # (1)!
)

english_agent = Agent(
    name="English agent",
    instructions="You only speak English",
    model=OpenAIChatCompletionsModel( # (2)!
        model="gpt-5-nano",
        openai_client=AsyncOpenAI()
    ),
)

triage_agent = Agent(
    name="Triage agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[spanish_agent, english_agent],
    model="gpt-5",
)

async def main():
    result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
    print(result.final_output)

OpenAI 모델의 이름을 직접 설정합니다
Model 구현을 제공합니다

에이전트에 사용하는 모델을 더 세부적으로 구성하려면, 온도(temperature)와 같은 선택적 모델 구성 매개변수를 제공하는 ModelSettings를 전달할 수 있습니다.

from agents import Agent, ModelSettings

english_agent = Agent(
    name="English agent",
    instructions="You only speak English",
    model="gpt-4.1",
    model_settings=ModelSettings(temperature=0.1),
)

또한 OpenAI의 Responses API를 사용할 때 다른 선택적 매개변수(예: user, service_tier 등)들이 있습니다. 최상위에서 제공되지 않는 경우 extra_args를 사용해 함께 전달할 수 있습니다.

from agents import Agent, ModelSettings

english_agent = Agent(
    name="English agent",
    instructions="You only speak English",
    model="gpt-4.1",
    model_settings=ModelSettings(
        temperature=0.1,
        extra_args={"service_tier": "flex", "user": "user_12345"},
    ),
)

다른 LLM 제공자 사용 시 일반적인 문제

트레이싱 클라이언트 오류 401

트레이싱 관련 오류가 발생한다면, 이는 트레이스가 OpenAI 서버로 업로드되는데 OpenAI API 키가 없기 때문입니다. 해결 방법은 다음 세 가지입니다:

트레이싱을 완전히 비활성화: set_tracing_disabled(True)
트레이싱 전용 OpenAI 키 설정: set_tracing_export_api_key(...). 이 API 키는 트레이스 업로드에만 사용되며, platform.openai.com에서 발급된 키여야 합니다
비 OpenAI 트레이스 프로세서를 사용. tracing docs를 참조하세요

Responses API 지원

SDK는 기본적으로 Responses API를 사용하지만, 대부분의 다른 LLM 제공자는 아직 이를 지원하지 않습니다. 이로 인해 404 등의 문제가 발생할 수 있습니다. 해결 방법은 다음 두 가지입니다:

set_default_openai_api("chat_completions")를 호출하세요. 환경 변수로 OPENAI_API_KEY와 OPENAI_BASE_URL을 설정하는 경우에 동작합니다
OpenAIChatCompletionsModel을 사용하세요. 예시는 여기에 있습니다

structured outputs 지원

일부 모델 제공자는 structured outputs을 지원하지 않습니다. 이로 인해 다음과 비슷한 오류가 발생할 수 있습니다:

BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' : value is not one of the allowed values ['text','json_object']", 'type': 'invalid_request_error'}}

이는 일부 모델 제공자의 한계입니다. JSON 출력을 지원하더라도 출력에 사용할 json_schema를 지정하도록 허용하지 않는 경우가 있습니다. 이에 대한 수정 작업을 진행 중이지만, JSON 스키마 출력을 지원하는 제공자에 의존할 것을 권장합니다. 그렇지 않으면 잘못된 JSON으로 인해 앱이 자주 깨질 수 있습니다.

제공자 간 모델 혼합 사용

모델 제공자 간의 기능 차이를 인지하지 못하면 오류가 발생할 수 있습니다. 예를 들어, OpenAI는 structured outputs, 멀티모달 입력, 호스팅되는 파일 검색과 웹 검색을 지원하지만, 다른 많은 제공자는 이러한 기능을 지원하지 않습니다. 다음 제한 사항에 유의하세요:

지원하지 않는 제공자에게는 지원되지 않는 tools를 보내지 않기
텍스트 전용 모델을 호출하기 전에 멀티모달 입력을 필터링하기
structured JSON 출력을 지원하지 않는 제공자는 때때로 잘못된 JSON을 생성할 수 있음을 인지하기