모델

모든 에이전트는 궁극적으로 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 프로바이더 구성

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 클라이언트를 연결할 수도 있습니다.

Responses WebSocket 전송

OpenAI 프로바이더를 Responses API와 함께 사용할 때, 기본 HTTP 전송 대신 WebSocket 전송으로 요청을 보낼 수 있습니다.

setOpenAIResponsesTransport('websocket')으로 전역 활성화하거나, new OpenAIProvider({ useResponses: true, useResponsesWebSocket: true })로 프로바이더 단위 활성화하세요.

WebSocket 전송만 사용하려면 withResponsesWebSocketSession(...)이나 커스텀 OpenAIProvider가 필요하지 않습니다. 실행/요청마다 재연결이 괜찮다면, setOpenAIResponsesTransport('websocket') 활성화 후 기존 run() / Runner.run() 사용은 계속 동작합니다.

연결 재사용을 최적화하고 WebSocket 프로바이더 수명 주기를 더 명시적으로 관리하려는 경우에만 withResponsesWebSocketSession(...) 또는 커스텀 OpenAIProvider / Runner를 사용하세요:

• withResponsesWebSocketSession(...): 콜백 종료 후 자동 정리를 포함한 편리한 범위 기반 수명 주기
• 커스텀 OpenAIProvider / Runner: 앱 아키텍처에서 명시적 수명 주기 제어(종료 시 정리 포함)

이름과 달리, withResponsesWebSocketSession(...)은 전송 수명 주기 헬퍼이며, 세션 가이드에 설명된 메모리 Session 인터페이스와는 관련이 없습니다.

WebSocket 프록시나 게이트웨이를 사용하는 경우, OpenAIProvider의 websocketBaseURL을 구성하거나 OPENAI_WEBSOCKET_BASE_URL을 설정하세요.

직접 OpenAIProvider를 인스턴스화하는 경우, 연결 재사용을 위해 WebSocket 기반 Responses 모델 래퍼가 기본적으로 캐시된다는 점을 기억하세요. 종료 시 await provider.close()를 호출하여 해당 캐시된 연결을 해제하세요. withResponsesWebSocketSession(...)은 주로 그 수명 주기를 관리하기 위해 존재합니다. WebSocket 활성화된 프로바이더와 러너를 생성해 콜백에 전달하고, 이후 항상 프로바이더를 닫습니다. 임시 프로바이더에는 providerOptions를, 콜백 범위 러너 기본값에는 runnerConfig를 사용하세요.

Responses WebSocket 전송을 사용하는 전체 스트리밍 + HITL 예시는 examples/basic/stream-ws.ts를 참고하세요.

---

모델 동작과 프롬프트

ModelSettings

ModelSettings는 OpenAI 매개변수를 반영하지만, 프로바이더에 독립적입니다.

필드	타입	비고
temperature	number	창의성 대 결정론
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를 사용할 때만 지원됩니다.

필드	타입	비고
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);
});

도구나 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 키와 다른 자격 증명을 사용해야 할 때만 setTracingExportApiKey()를 사용하세요:

트레이싱 내보내기 API 키 설정

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

setTracingExportApiKey('sk-...');

이는 해당 자격 증명을 사용해 OpenAI 대시보드로 트레이스를 전송합니다. 사용자 지정 수집 엔드포인트나 재시도 튜닝 같은 내보내기자 커스터마이징은 트레이싱 가이드를 참고하세요.

---

다음 단계

• 에이전트 실행을 탐색하세요
• 도구로 모델에 강력한 기능을 부여하세요
• 필요에 따라 가드레일 또는 트레이싱을 추가하세요