모델

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

• Model – 특정 API에 대해 요청을 한 번 수행하는 방법을 알고 있습니다.
• ModelProvider – 사람이 읽을 수 있는 모델 이름(예: 'gpt‑5.2')을 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.2
node my-awesome-agent.js

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

Runner에 기본 모델 설정

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

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

GPT-5.x 모델

이 방식으로 gpt-5.2 같은 GPT-5.x 모델을 사용할 때, SDK는 기본 modelSettings를 적용합니다. 대부분의 사용 사례에서 가장 잘 작동하는 설정을 사용합니다. 기본 모델의 추론 강도를 조정하려면 사용자 정의 modelSettings를 전달하세요:

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

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

const myAgent = new Agent({
  name: 'My Agent',
  instructions: "You're a helpful agent.",
  // If OPENAI_DEFAULT_MODEL=gpt-5.2 is set, passing only modelSettings works.
  // It's also fine to pass a GPT-5.x model name explicitly:
  model: 'gpt-5.2',
  modelSettings: {
    reasoning: { effort: 'high' },
    text: { verbosity: 'low' },
  },
});

더 낮은 지연 시간을 위해 gpt-5.2에 reasoning.effort: "none" 사용을 권장합니다. gpt-4.1 계열(미니 및 나노 버전 포함)도 대화형 에이전트 앱을 구축하는 데 여전히 좋은 선택입니다.

비 GPT-5 모델

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

---

OpenAI 프로바이더

기본 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	창의성 vs 결정론
topP	number	누클리어스 샘플링
frequencyPenalty	number	반복 토큰 페널티
presencePenalty	number	새로운 토큰 장려
toolChoice	'auto' | 'required' | 'none' | string	도구 사용 강제 참조
parallelToolCalls	boolean	지원되는 경우 병렬 함수 호출 허용
truncation	'auto' | 'disabled'	토큰 절단 전략
maxTokens	number	응답의 최대 토큰 수
store	boolean	검색/RAG 워크플로우를 위해 응답을 저장
promptCacheRetention	'in-memory' | '24h' | null	지원되는 경우 프로바이더 프롬프트 캐시 보존 제어
reasoning.effort	'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'	gpt-5.x 모델의 추론 강도
reasoning.summary	'auto' | 'concise' | 'detailed'	모델이 반환하는 추론 요약의 양을 제어
text.verbosity	'low' | 'medium' | 'high'	gpt-5.x 등의 텍스트 장황함
providerData	Record<string, any>	기본 모델로 전달되는 프로바이더별 패스스루 옵션

설정은 어느 수준에든 첨부할 수 있습니다:

모델 설정

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 { parseArgs } from 'node:util';
import { Agent, run } from '@openai/agents';

/*
NOTE: This example will not work out of the box, because the default prompt ID will not
be available in your project.

To use it, please:
1. Go to https://platform.openai.com/chat/edit
2. Create a new prompt variable, `poem_style`.
3. Create a system prompt with the content:
   Write a poem in {{poem_style}}
4. Run the example with the `--prompt-id` flag.
*/

const DEFAULT_PROMPT_ID =
  'pmpt_6965a984c7ac8194a8f4e79b00f838840118c1e58beb3332';
const POEM_STYLES = ['limerick', 'haiku', 'ballad'];

function pickPoemStyle(): string {
  return POEM_STYLES[Math.floor(Math.random() * POEM_STYLES.length)];
}

async function runDynamic(promptId: string) {
  const poemStyle = pickPoemStyle();
  console.log(`[debug] Dynamic poem_style: ${poemStyle}`);

  const agent = new Agent({
    name: 'Assistant',
    prompt: {
      promptId,
      version: '1',
      variables: { poem_style: poemStyle },
    },
  });

  const result = await run(agent, 'Tell me about recursion in programming.');
  console.log(result.finalOutput);
}

async function runStatic(promptId: string) {
  const agent = new Agent({
    name: 'Assistant',
    prompt: {
      promptId,
      version: '1',
      variables: { poem_style: 'limerick' },
    },
  });

  const result = await run(agent, 'Tell me about recursion in programming.');
  console.log(result.finalOutput);
}

async function main() {
  const args = parseArgs({
    options: {
      dynamic: { type: 'boolean', default: false },
      'prompt-id': { type: 'string', default: DEFAULT_PROMPT_ID },
    },
  });

  const promptId = args.values['prompt-id'];
  if (!promptId) {
    console.error('Please provide a prompt ID via --prompt-id.');
    process.exit(1);
  }

  if (args.values.dynamic) {
    await runDynamic(promptId);
  } else {
    await runStatic(promptId);
  }
}

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

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

---

사용자 지정 모델 프로바이더

직접 프로바이더를 구현하는 것은 간단합니다 – ModelProvider와 Model을 구현하고 프로바이더를 Runner 생성자에 전달하세요:

최소한의 커스텀 프로바이더

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 이외의 모델에 대한 준비된 어댑터가 필요하다면, AI SDK로 어떤 모델이든 사용을 확인하세요.

---

트레이싱 익스포터

OpenAI 프로바이더를 사용할 때 API 키를 제공하여 자동 트레이스 내보내기를 옵트인할 수 있습니다:

트레이싱 익스포터

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

setTracingExportApiKey('sk-...');

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

---

다음 단계

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