모델

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

Model – 특정 API에 대해 한 번의 요청을 보내는 방법을 알고 있습니다.
ModelProvider – 사람이 읽기 쉬운 모델 이름(예: 'gpt‑5.4')을 Model 인스턴스로 해석합니다.

일상적인 작업에서는 보통 모델 이름만 다루고, 가끔 ModelSettings를 다룹니다.

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

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

모델 선택

기본 모델

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

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

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

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

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

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

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

GPT-5.x 모델

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

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

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

지연 시간이 중요하다면 gpt-5.4에서 reasoning.effort: "none"으로 시작하고, 작업에 더 신중한 추론이 필요할 때만 높이세요. gpt-4.1 계열( mini 및 nano 변형 포함)도 대화형 에이전트 앱 구축에 여전히 견고한 선택입니다.

비 GPT-5 모델

사용자 지정 modelSettings 없이 GPT-5가 아닌 모델 이름을 전달하면 SDK는 모든 모델과 호환되는 일반 modelSettings로 되돌아갑니다.

OpenAI provider 구성

OpenAI provider

기본 ModelProvider는 OpenAI API를 사용해 이름을 해석합니다. 서로 다른 두 엔드포인트를 지원합니다:

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

인증

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

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

커스텀 네트워킹 설정이 필요하다면 setDefaultOpenAIClient(client)를 통해 자체 OpenAI 클라이언트를 연결할 수도 있습니다.

Responses WebSocket 전송

Responses API와 함께 OpenAI provider를 사용하면 기본 HTTP 전송 대신 WebSocket 전송으로 요청을 보낼 수 있습니다.

전역으로는 setOpenAIResponsesTransport('websocket')로 활성화하고, provider별로는 new OpenAIProvider({ useResponses: true, useResponsesWebSocket: true })로 활성화할 수 있습니다.

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

전송 방식 선택은 모델 해석을 따릅니다:

setOpenAIResponsesTransport('websocket')는 Responses API 사용 시, 이후 OpenAI provider를 통해 해석되는 문자열 모델 이름에만 영향을 줍니다.
Agent 또는 Runner에 구체적인 Model 인스턴스를 전달하면 해당 인스턴스를 그대로 사용합니다. OpenAIResponsesWSModel은 WebSocket을, OpenAIResponsesModel은 HTTP를, OpenAIChatCompletionsModel은 Chat Completions를 유지합니다.
자체 modelProvider를 제공하면 모델 해석은 해당 provider가 제어합니다. 전역 설정에 의존하지 말고 그곳에서 WebSocket을 활성화하세요.
프록시, 게이트웨이 또는 기타 OpenAI 호환 엔드포인트를 거치는 경우 대상이 WebSocket /responses 엔드포인트를 지원해야 합니다. websocketBaseURL을 명시적으로 설정해야 할 수도 있습니다.

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

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

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

websocket 프록시 또는 게이트웨이를 사용한다면 OpenAIProvider의 websocketBaseURL을 설정하거나 OPENAI_WEBSOCKET_BASE_URL을 설정하세요.

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

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

Responses 전용 지연 도구 로딩

toolSearchTool(), toolNamespace(), 그리고 deferLoading: true를 설정한 함수 도구 또는 호스티드 MCP 서버 도구는 OpenAI Responses API가 필요합니다. Chat Completions provider는 네임스페이스 도구 또는 지연 함수 도구를 거부하며, AI SDK 어댑터는 지연 Responses 도구 로딩 흐름을 지원하지 않습니다. 도구 검색이 필요하면 Responses 모델을 직접 사용하세요.

도구 검색은 GPT-5.4 및 Responses API에서 이를 지원하는 이후 모델 릴리스에서만 지원됩니다.

실행에 지연 도구가 포함되면 동일한 에이전트에 toolSearchTool()을 추가하고 modelSettings.toolChoice를 'auto'로 유지하세요. SDK는 모델이 해당 정의를 언제 로드할지 결정해야 하므로 내장 tool_search 도구나 지연 함수 도구를 이름으로 강제할 수 없게 합니다. 전체 설정은 도구 가이드 및 공식 OpenAI tool search guide를 참고하세요.

모델 동작과 프롬프트

ModelSettings

ModelSettings는 OpenAI 매개변수를 반영하지만 provider에 종속되지 않습니다.

필드	타입	참고
`temperature`	`number`	창의성 대 결정성
`topP`	`number`	뉴클리어스 샘플링
`frequencyPenalty`	`number`	반복 토큰에 패널티 부여
`presencePenalty`	`number`	새로운 토큰 생성 장려
`toolChoice`	`'auto' \| 'required' \| 'none' \| string`	도구 사용 강제 참고. OpenAI Responses에서 `toolChoice: 'computer'`는 사용 가능할 때 GA 내장 컴퓨터 도구를 강제합니다
`parallelToolCalls`	`boolean`	지원되는 경우 병렬 함수 호출 허용
`truncation`	`'auto' \| 'disabled'`	토큰 잘림 전략
`maxTokens`	`number`	응답의 최대 토큰 수
`store`	`boolean`	조회 / RAG 워크플로를 위해 응답 저장
`promptCacheRetention`	`'in-memory' \| '24h' \| null`	지원되는 경우 provider 프롬프트 캐시 보존 제어
`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>`	기본 모델로 전달되는 provider별 패스스루 옵션
`retry`	`ModelRetrySettings`	런타임 전용 옵트인 재시도 구성. 모델 재시도 참고

설정은 두 수준 중 어느 곳이든 적용할 수 있습니다:

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 수준 설정은 에이전트별 설정과 충돌하는 값을 덮어씁니다. 예외적으로 retry는 상속된 값을 undefined로 명시적으로 지우지 않는 한 runner와 agent 설정 간 중첩 필드가 병합됩니다.

모델 재시도

재시도는 런타임 전용이며 옵트인입니다. modelSettings.retry를 구성하고 정책이 재시도 결정을 반환하지 않으면 SDK는 모델 요청을 재시도하지 않습니다.

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

const sharedRetry = {
  maxRetries: 4,
  backoff: {
    initialDelayMs: 500,
    maxDelayMs: 5_000,
    multiplier: 2,
    jitter: true,
  },
  policy: retryPolicies.any(
    retryPolicies.providerSuggested(),
    retryPolicies.retryAfter(),
    retryPolicies.networkError(),
    retryPolicies.httpStatus([408, 409, 429, 500, 502, 503, 504]),
  ),
};

const runner = new Runner({
  modelSettings: {
    retry: sharedRetry,
  },
});

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a concise assistant.',
  modelSettings: {
    retry: {
      maxRetries: 2,
      backoff: {
        maxDelayMs: 2_000,
      },
    },
  },
});

await runner.run(agent, 'Summarize exponential backoff in plain English.');

ModelRetrySettings에는 세 가지 필드가 있습니다:

필드	타입	참고
`maxRetries`	`number`	초기 요청 이후 허용되는 재시도 횟수
`backoff`	`{ initialDelayMs?, maxDelayMs?, multiplier?, jitter? }`	정책이 `delayMs`를 반환하지 않고 재시도할 때의 기본 지연 전략
`policy`	`RetryPolicy`	재시도 여부를 결정하는 콜백. 이 함수는 런타임 전용이며 저장된 실행 상태로 직렬화되지 않습니다

재시도 정책은 다음을 포함한 RetryPolicyContext를 받습니다:

시도 횟수 기반 결정을 위한 attempt 및 maxRetries
스트리밍/비스트리밍 분기를 위한 stream
원문 검사용 error
statusCode, retryAfterMs, errorCode, isNetworkError, isAbort 같은 정규화된 정보 normalized
기본 모델/provider가 재시도 가이드를 제공할 수 있을 때의 providerAdvice

정책은 다음 중 하나를 반환할 수 있습니다:

단순 재시도 결정을 위한 true / false
지연을 덮어쓰거나 로깅용 진단 사유를 붙이기 위한 { retry, delayMs?, reason? }

SDK는 retryPolicies에 준비된 헬퍼를 제공합니다:

헬퍼	동작
`retryPolicies.never()`	항상 옵트아웃
`retryPolicies.providerSuggested()`	가능할 때 provider 재시도 권고를 따름
`retryPolicies.networkError()`	일시적 전송/연결 실패와 매칭
`retryPolicies.httpStatus([..])`	선택한 HTTP 상태 코드와 매칭
`retryPolicies.retryAfter()`	retry-after 힌트가 있을 때만 해당 지연으로 재시도
`retryPolicies.any(...)`	중첩 정책 중 하나라도 옵트인하면 재시도
`retryPolicies.all(...)`	모든 중첩 정책이 옵트인할 때만 재시도

정책을 조합할 때 providerSuggested()는 provider가 구분할 수 있는 거부 신호와 재실행 안전 승인 신호를 보존하므로 가장 안전한 첫 구성 요소입니다.

안전 경계

일부 실패는 자동 재시도되지 않습니다:

Abort 오류
가시 이벤트 또는 원문 모델 이벤트가 이미 하나라도 방출된 이후의 스트리밍 실행
재실행이 안전하지 않다고 표시한 provider 권고

previousResponseId 또는 conversationId를 사용하는 상태 기반 후속 요청도 더 보수적으로 처리됩니다. 이런 요청에서는 networkError()나 httpStatus([500]) 같은 비 provider 조건만으로는 충분하지 않습니다. 재시도 정책에는 보통 retryPolicies.providerSuggested()를 통한 provider의 재실행 안전 승인이 포함되어야 합니다.

Runner와 agent 병합 동작

retry는 runner 수준과 agent 수준 modelSettings 사이에서 깊은 병합이 됩니다:

에이전트는 retry.maxRetries만 덮어쓰고 runner의 policy를 계속 상속할 수 있습니다
에이전트는 retry.backoff의 일부만 덮어쓰고 나머지 backoff 필드는 runner 값을 유지할 수 있습니다
상속된 policy나 backoff를 제거해야 하면 해당 필드를 명시적으로 undefined로 설정하세요

로깅을 포함한 더 완전한 예시는 examples/basic/retry.ts 및 examples/ai-sdk/retry.ts를 참고하세요.

프롬프트

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

prompt는 정적 객체이거나 런타임에 객체를 반환하는 함수일 수 있습니다. 콜백 형태는 동적 프롬프트를 참고하세요.

필드	타입	참고
`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 같은 추가 에이전트 구성은 저장된 프롬프트에 설정했을 수 있는 값을 덮어씁니다.

저장된 프롬프트가 이미 모델을 정의하고 있으면, 명시적으로 덮어쓰지 않는 한 SDK는 에이전트 기본 모델을 전송하지 않습니다. 이는 computerTool()에서 중요합니다: 프롬프트 관리 실행은 호환성을 위해 기본적으로 레거시 프리뷰 wire 형식을 유지합니다. 프롬프트 관리 실행에서 GA Responses 컴퓨터 도구를 사용하려면 modelSettings.toolChoice: 'computer'를 명시적으로 설정하거나 gpt-5.4 같은 명시적 모델을 전송하세요. 관련 컴퓨터 사용 세부사항은 도구를 참고하세요.

고급 provider 및 관찰 가능성

커스텀 모델 provider

직접 provider를 구현하는 것은 간단합니다. ModelProvider와 Model을 구현하고 provider를 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);

모든 run() 호출과 새로 생성되는 모든 Runner가 기본적으로 동일한 provider를 사용하게 하려면 앱 시작 시 한 번 설정하세요:

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

setDefaultModelProvider({
  async getModel() {
    // Return any Model implementation here.
    throw new Error('Provide your own model implementation.');
  },
});

앱이 OpenAI가 아닌 provider를 표준으로 사용하고 모든 곳에 커스텀 Runner를 전달하고 싶지 않을 때 유용합니다.

AI SDK 연동

직접 ModelProvider를 구현하지 않고 OpenAI가 아닌 모델을 사용하려면 Vercel의 AI SDK로 임의 모델 사용을 참고하세요. 이 어댑터는 AI SDK 모델을 Agents 런타임에 직접 연결할 수 있게 해주며, 앱이 이미 AI SDK provider를 표준으로 사용하거나 더 넓은 provider 생태계에 접근하려는 경우 유용합니다. 또한 Agents SDK providerData가 AI SDK providerMetadata에 어떻게 매핑되는지, AI SDK UI 라우트에서 사용할 수 있는 스트림 헬퍼도 문서화합니다.

트레이싱 자격 증명

지원되는 서버 런타임에서는 트레이싱이 이미 기본 활성화되어 있습니다. trace 내보내기에 기본 OpenAI API 키와 다른 자격 증명을 써야 할 때만 setTracingExportApiKey()를 사용하세요:

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

setTracingExportApiKey('sk-...');

이렇게 하면 해당 자격 증명으로 OpenAI dashboard에 트레이스를 보냅니다. 커스텀 수집 엔드포인트나 재시도 튜닝 같은 exporter 사용자 지정은 트레이싱 가이드를 참고하세요.

다음 단계

에이전트 실행을 살펴보세요
도구로 모델에 강력한 기능을 추가하세요
필요에 따라 가드레일 또는 트레이싱을 추가하세요