모델
Agents SDK는 두 가지 방식으로 OpenAI 모델을 바로 사용할 수 있도록 지원합니다:
OpenAI 모델
Agent를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 호환성과 낮은 지연 시간을 위해gpt-4.1입니다. 접근 권한이 있다면 더 높은 품질을 위해 에이전트를gpt-5.2로 설정하고model_settings는 명시적으로 유지할 것을 권장합니다.
gpt-5.2와 같은 다른 모델로 전환하려면 다음 섹션의 단계를 따르세요.
기본 OpenAI 모델
사용자 지정 모델을 설정하지 않은 모든 에이전트에 대해 일관되게 특정 모델을 사용하려면, 에이전트를 실행하기 전에OPENAI_DEFAULT_MODEL 환경 변수를 설정하세요.
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를 전달하세요:
fromopenai.types.sharedimportReasoningfromagentsimportAgent,ModelSettingsmy_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 의존성 그룹을 설치하세요:
그런 다음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 두 형태를 모두 지원하지만, 두 형태가 지원하는 기능과 도구가 다르므로 각 워크플로에서는 단일 모델 형태를 사용할 것을 권장합니다. 워크플로가 모델 형태의 혼합을 필요로 하는 경우, 사용하는 모든 기능이 양쪽에서 모두 제공되는지 확인하세요.
fromagentsimportAgent,Runner,AsyncOpenAI,OpenAIChatCompletionsModelimportasynciospanish_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",)asyncdefmain():result=awaitRunner.run(triage_agent,input="Hola, ¿cómo estás?")print(result.final_output)- OpenAI 모델의 이름을 직접 설정합니다
Model구현을 제공합니다
에이전트에 사용하는 모델을 더 세부적으로 구성하려면, 온도(temperature)와 같은 선택적 모델 구성 매개변수를 제공하는ModelSettings를 전달할 수 있습니다.
fromagentsimportAgent,ModelSettingsenglish_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를 사용해 함께 전달할 수 있습니다.
fromagentsimportAgent,ModelSettingsenglish_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을 생성할 수 있음을 인지하기