모델과 제공자

모델과 제공자 (Models and providers)

모든 SDK 실행은 결국 모델과 전송(transport)을 해결해요. 대부분의 애플리케이션은 그 설정을 단순하게 유지해야 해요. 모델을 명시적으로 선택하고 기본적으로 표준 OpenAI 경로를 사용하며, 워크플로우가 실제로 필요할 때만 제공자 또는 전송 재정의를 사용하세요.

출처: 문서

본문

모든 SDK 실행은 결국 모델과 전송을 해결해요. 대부분의 애플리케이션은 그 설정을 단순하게 유지해야 해요. 모델을 명시적으로 선택하고 기본적으로 표준 OpenAI 경로를 사용하며, 워크플로우가 실제로 필요할 때만 제공자 또는 전송 재정의를 사용하세요.

명시적 모델 선택으로 시작하기

프로덕션에서는 SDK 릴리스가 기본으로 제공하는 런타임 기본값보다 명시적 모델 선택을 선호하세요.

그 전문가가 일관되게 다른 품질, 지연 시간, 비용 프로필을 필요로 할 때 에이전트에 model을 설정하세요.
한 워크플로우가 여러 에이전트를 한 번에 재정의해야 할 때 실행 수준 기본값을 설정하세요.
model을 생략한 에이전트를 위한 프로세스 전반의 폴백을 원할 때 OPENAI_DEFAULT_MODEL을 설정하세요.

에이전트별 및 실행별 모델 설정하기

import { Agent, Runner } from "@openai/agents";

const fastAgent = new Agent({
  name: "Fast support agent",
  instructions: "Handle routine support questions.",
  model: "gpt-5.6-terra",
});

const generalAgent = new Agent({
  name: "General support agent",
  instructions: "Handle support questions carefully.",
});

const runner = new Runner({
  model: "gpt-6-astra",
});

await runner.run(fastAgent, "Summarize ticket 123.");
const result = await runner.run(
  generalAgent,
  "Investigate the billing issue on account 456."
);

console.log(result.finalOutput);

import asyncio

from agents import Agent, RunConfig, Runner

fast_agent = Agent(
    name="Fast support agent",
    instructions="Handle routine support questions.",
    model="gpt-5.6-terra",
)

general_agent = Agent(
    name="General support agent",
    instructions="Handle support questions carefully.",
)


async def main() -> None:
    await Runner.run(fast_agent, "Summarize ticket 123.")

    result = await Runner.run(
        general_agent,
        "Investigate the billing issue on account 456.",
        run_config=RunConfig(model="gpt-6-astra"),
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

대부분의 새 SDK 워크플로우에서는 gpt-6-astra로 시작하고, 지연 시간이나 비용이 이를 정당화할 만큼 중요할 때만 더 작은 변형으로 이동하세요. 현재 모델 선택 조언은 플랫폼 전반의 Model guidance 페이지를 사용하세요.

가장 단순한 기본 전략 선택하기

필요한 경우	시작할 것	이유
전문가별 하나의 명시적 모델	각 에이전트에 `model` 설정	워크플로우가 코드와 트레이스에서 읽기 쉽게 유지돼요
전체 프로세스에 걸친 하나의 폴백	`OPENAI_DEFAULT_MODEL`	`model`을 생략한 에이전트도 예측 가능하게 해결돼요
하나의 워크플로우 수준 재정의	실행 수준 기본값	스크립트, 워커, 환경마다 모든 에이전트를 편집하지 않고 모델을 바꿀 수 있어요
동일 워크플로우에서 다른 모델 크기	에이전트별 모델 혼합	빠른 분류(triage) 에이전트와 느린 심층 전문가가 깔끔하게 공존할 수 있어요

팀이 정확한 기본값을 신경 쓴다면 SDK 폴백에 의존하지 말고 직접 설정하세요.

제공자와 전송 (Providers and transport)

필요한 경우	시작할 것
OpenAI에서 표준 SDK 실행	기본 OpenAI 제공자 경로
소켓을 통한 반복된 Responses 모델 왕복	SDK의 Responses WebSocket 전송
비-OpenAI 모델 또는 혼합 제공자 스택	언어별 SDK 문서의 제공자 또는 어댑터 표면

두 가지 구분이 중요해요:

Responses WebSocket 전송은 여전히 일반적인 텍스트와 도구 에이전트 루프를 사용해요. 음성 세션 경로와는 별개예요.
WebRTC 또는 WebSocket을 통한 실시간 오디오 세션은 저지연 음성 또는 이미지 상호작용을 위한 것이에요. 그 경로에는 Voice agents와 live audio API guide를 사용하세요.

정확한 제공자 설정, 제공자 수명 주기 관리, 전송 헬퍼 API는 언어별 자료로 남아 있어요. 그 세부 사항을 여기 복제하는 대신 SDK 문서에 두세요.

모델 설정, 프롬프트, 기능 지원

모델 선택은 런타임 계약의 일부일 뿐이에요.

추론 노력, 장황함, 도구 동작 같은 튜닝에는 TypeScript의 modelSettings 또는 Python의 model_settings를 사용하세요.
코드에 전체 시스템 프롬프트를 내장하는 대신 저장된 프롬프트 설정이 실행을 제어하게 하려면 prompt를 사용하세요.
일부 SDK 기능은 이전 호환 표면이 아닌 OpenAI Responses 경로에 의존하므로, 고급 도구 로딩이나 전송 기능이 필요하면 SDK 문서를 확인하세요.

모델 계약이 그 전문가에게 본질적일 때는 에이전트 정의 가까이에 두세요. 여러 에이전트가 같은 런타임 선택을 공유해야 할 때만 워크플로우 수준 기본값으로 이동하세요.

다음 단계

런타임 계약이 명확해지면 나머지 워크플로우 설계와 일치하는 가이드로 계속 진행하세요.

[Agent definitions

    Keep model choices aligned with the responsibilities of each specialist.](https://developers.openai.com/api/docs/guides/agents/define-agents)

[Running agents

    See how transport and model choices affect the runtime loop.](https://developers.openai.com/api/docs/guides/agents/running-agents)

[External models

    Compare broader provider options when a mixed-model stack matters.](https://developers.openai.com/api/docs/guides/external-models)

더 알아보기 (Learn more)

관련 문서: 에이전트 정의와 에이전트 실행을 참고하세요.