모델

모든 에이전트는 궁극적으로 LLM을 호출합니다. SDK는 두 가지 경량 인터페이스 뒤로 모델을 추상화합니다:

• Model – 특정 API에 대해 하나의 요청을 수행하는 방법을 알고 있음
• ModelProvider – 사람이 읽을 수 있는 모델 이름(예: 'gpt‑4o')을 Model 인스턴스로 해석

일상적인 작업에서는 일반적으로 모델 이름만 다루며, 때때로 ModelSettings를 사용합니다.

에이전트별 모델 지정

import { Agent } from '@openai/agents';

const agent = new Agent({
  name: 'Creative writer',
  model: 'gpt-5.2',
});

기본 모델

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

gpt-5.2 같은 다른 모델로 전환하려면, 에이전트를 구성하는 방법은 두 가지가 있습니다.

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

export OPENAI_DEFAULT_MODEL=gpt-5
node my-awesome-agent.js

둘째, Runner 인스턴스에 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 Runner의 기본 모델이 사용됩니다.

Runner에 기본 모델 설정

import { Runner } from '@openai/agents';

const runner = new Runner({ model: 'gpt‑4.1-mini' });

GPT-5 모델

이 방식으로 GPT-5의 추론 모델(gpt-5, gpt-5-mini, gpt-5-nano)을 사용할 때, SDK는 합리적인 modelSettings를 기본으로 적용합니다. 구체적으로, reasoning.effort와 verbosity를 모두 "low"로 설정합니다. 기본 모델의 추론 강도를 조정하려면, 사용자 정의 modelSettings를 전달하세요:

GPT-5 기본 설정 사용자 지정

import { Agent } from '@openai/agents';

const myAgent = new Agent({
  name: 'My Agent',
  instructions: "You're a helpful agent.",
  modelSettings: {
    reasoning: { effort: 'minimal' },
    text: { verbosity: 'low' },
  },
  // If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only modelSettings 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 모델

사용자 정의 modelSettings 없이 비 GPT-5 모델 이름을 전달하면, SDK는 모든 모델과 호환되는 일반적인 modelSettings로 되돌립니다.

---

OpenAI provider

기본 ModelProvider는 OpenAI API를 사용해 이름을 해석합니다. 두 가지 구분되는 엔드포인트를 지원합니다:

API	용도	setOpenAIAPI() 호출
Chat Completions	표준 채팅 및 함수 호출	setOpenAIAPI('chat_completions')
Responses	스트리밍 우선의 새로운 생성 API(도구 호출, 유연한 출력)	setOpenAIAPI('responses') (기본값)

인증

기본 OpenAI 키 설정

import { setDefaultOpenAIKey } from '@openai/agents';

setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

맞춤 네트워킹 설정이 필요한 경우 setDefaultOpenAIClient(client)를 통해 사용자 고유의 OpenAI 클라이언트를 연결할 수도 있습니다.

---

ModelSettings

ModelSettings는 OpenAI 매개변수를 반영하지만, 공급자에 구애받지 않습니다.

Field	Type	Notes
temperature	number	창의성 대 결정론
topP	number	누클리어스 샘플링
frequencyPenalty	number	반복 토큰에 패널티 부여
presencePenalty	number	새로운 토큰 사용 장려
toolChoice	'auto' | 'required' | 'none' | string	도구 사용 강제 참고
parallelToolCalls	boolean	지원되는 경우 병렬 함수 호출 허용
truncation	'auto' | 'disabled'	토큰 절단 전략
maxTokens	number	응답의 최대 토큰 수
store	boolean	검색/RAG 워크플로를 위해 응답을 저장
reasoning.effort	'minimal' | 'low' | 'medium' | 'high'	gpt-5 등용 추론 강도
text.verbosity	'low' | 'medium' | 'high'	gpt-5 등용 텍스트 장황도

설정은 어느 레벨에나 부착할 수 있습니다:

모델 설정

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

const agent = new Agent({
  name: 'Creative writer',
  // ...
  modelSettings: { temperature: 0.7, toolChoice: 'auto' },
});

// or globally
new Runner({ modelSettings: { temperature: 0.3 } });

Runner 레벨의 설정은 충돌하는 에이전트별 설정을 무시합니다.

---

프롬프트

에이전트는 prompt 매개변수로 구성할 수 있으며, 이는 서버에 저장된 프롬프트 구성을 사용해 에이전트의 동작을 제어해야 함을 나타냅니다. 현재 이 옵션은 OpenAI Responses API를 사용할 때만 지원됩니다.

Field	Type	Notes
promptId	string	프롬프트의 고유 식별자
version	string	사용하려는 프롬프트 버전
variables	object	프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열 또는 텍스트, 이미지, 파일 같은 콘텐츠 입력 타입이 될 수 있음

프롬프트가 있는 에이전트

import { Agent, run } from '@openai/agents';

async function main() {
  const agent = new Agent({
    name: 'Assistant',
    prompt: {
      promptId: 'pmpt_68d50b26524c81958c1425070180b5e10ab840669e470fc7',
      variables: { name: 'Kaz' },
    },
  });

  const result = await run(agent, 'What is your name?');
  console.log(result.finalOutput);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

tools 또는 instructions 같은 추가 에이전트 구성은 저장된 프롬프트에 구성해 둔 값을 재정의합니다.

---

사용자 정의 모델 provider

사용자 정의 provider 구현은 간단합니다 – ModelProvider와 Model을 구현하고 provider를 Runner 생성자에 전달하면 됩니다:

최소한의 커스텀 provider

import {
  ModelProvider,
  Model,
  ModelRequest,
  ModelResponse,
  ResponseStreamEvent,
} from '@openai/agents-core';

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

class EchoModel implements Model {
  name: string;
  constructor() {
    this.name = 'Echo';
  }
  async getResponse(request: ModelRequest): Promise<ModelResponse> {
    return {
      usage: {},
      output: [{ role: 'assistant', content: request.input as string }],
    } as any;
  }
  async *getStreamedResponse(
    _request: ModelRequest,
  ): AsyncIterable<ResponseStreamEvent> {
    yield {
      type: 'response.completed',
      response: { output: [], usage: {} },
    } as any;
  }
}

class EchoProvider implements ModelProvider {
  getModel(_modelName?: string): Promise<Model> | Model {
    return new EchoModel();
  }
}

const runner = new Runner({ modelProvider: new EchoProvider() });
console.log(runner.config.modelProvider.getModel());
const agent = new Agent({
  name: 'Test Agent',
  instructions: 'You are a helpful assistant.',
  model: new EchoModel(),
  modelSettings: { temperature: 0.7, toolChoice: 'auto' },
});
console.log(agent.model);

---

트레이싱 익스포터

OpenAI provider를 사용할 때 API 키를 제공하여 자동 추적 내보내기에 옵트인할 수 있습니다:

트레이싱 익스포터

import { setTracingExportApiKey } from '@openai/agents';

setTracingExportApiKey('sk-...');

이는 OpenAI 대시보드로 트레이스를 전송하며, 워크플로의 전체 실행 그래프를 검사할 수 있습니다.

---

다음 단계

• 에이전트 실행을 살펴보세요
• 도구로 모델에 슈퍼 파워를 부여하세요
• 필요에 따라 가드레일 또는 트레이싱을 추가하세요