모델

모든 Agent는 결국 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를 적용합니다. 대부분의 사용 사례에서 가장 잘 작동하는 설정을 지정합니다. 기본 모델의 reasoning effort를 조정하려면 직접 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를 통해 해석되는 문자열 모델 이름에만 영향을 줍니다
구체적인 Model 인스턴스를 Agent나 Runner에 전달하면, 그 인스턴스가 그대로 사용됩니다. OpenAIResponsesWSModel은 WebSocket을 유지하고, OpenAIResponsesModel은 HTTP를 유지하며, OpenAIChatCompletionsModel은 Chat Completions를 유지합니다
자체 modelProvider를 제공하면, 해당 provider가 모델 해석을 제어합니다. 이 경우 전역 setter에 의존하지 말고 그 안에서 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 모델을 직접 사용하세요.

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

실행에 지연 도구가 포함되는 경우, 같은 에이전트에 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별 passthrough 옵션
`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 설정 전반에 걸쳐 병합됩니다.

모델 재시도

재시도는 런타임 전용이며 옵트인 방식입니다. SDK는 modelSettings.retry를 구성하고 정책이 재시도 결정을 반환하는 경우에만 모델 요청을 재시도합니다.

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가 이를 구분할 수 있을 때 provider의 veto와 재실행 안전성 승인을 보존하기 때문입니다.

안전 경계

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

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

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

Runner와 agent 병합 동작

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

에이전트는 retry.maxRetries만 재정의하고도 runner의 policy를 상속할 수 있습니다
에이전트는 retry.backoff의 일부만 재정의하고 runner의 형제 backoff 필드는 유지할 수 있습니다
상속된 policy 또는 backoff를 제거해야 한다면, 해당 필드를 명시적으로 undefined로 설정하세요

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

프롬프트

에이전트는 prompt 매개변수로 구성할 수 있으며, 이는 Agent의 동작을 제어하는 데 사용할 서버 저장 프롬프트 구성을 나타냅니다. 현재 이 옵션은 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);
});

tools나 instructions 같은 추가 에이전트 설정은 저장된 프롬프트에 구성해 둔 값을 덮어씁니다.

저장된 프롬프트가 이미 모델을 정의하고 있는 경우, 명시적으로 재정의하지 않으면 SDK는 에이전트의 기본 모델을 전송하지 않습니다. 이는 computerTool()에 중요합니다. 프롬프트 관리 실행은 호환성을 위해 기본적으로 레거시 preview wire shape를 유지합니다. 프롬프트 관리 실행에서 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 라우트에서 사용할 수 있는 스트림 헬퍼도 문서화되어 있습니다.

트레이싱 자격 증명

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

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

setTracingExportApiKey('sk-...');

이렇게 하면 해당 자격 증명을 사용해 트레이스를 OpenAI dashboard로 전송합니다. 사용자 지정 수집 엔드포인트나 재시도 조정 같은 exporter 사용자 지정은 트레이싱 가이드를 참고하세요.

다음 단계

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