모델

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

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

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

에이전트별 모델 지정

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

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

모델 선택

기본 모델

Agent를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 효율적인 대규모 에이전트 워크로드를 위해 reasoning.effort: "none" 및 text.verbosity: "low"로 설정된 gpt-5.6-luna입니다.

gpt-5.6-sol 같은 다른 모델로 전환하려면 두 가지 방법으로 에이전트를 설정할 수 있습니다.

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

export OPENAI_DEFAULT_MODEL=gpt-5.6-sol
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.6-sol 같은 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.6-sol is set, passing only modelSettings works.
  // It's also fine to pass a GPT-5.x model name explicitly:
  model: 'gpt-5.6-sol',
  modelSettings: {
    reasoning: { effort: 'high' },
    text: { verbosity: 'low' },
  },
});

지연 시간과 비용이 중요하다면 기본 gpt-5.6-luna 설정으로 시작하거나 다른 GPT-5.x 모델에서 reasoning.effort: "none"을 사용한 다음, 작업에 더 신중한 추론이 필요한 경우에만 추론 노력을 높이세요.

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 클라이언트를 연결할 수도 있습니다. 직접 제공하는 클라이언트는 openai 7.2 이상을 사용해야 합니다.

공급자 옵션 참고 자료

OpenAIProvider를 직접 인스턴스화할 때 다음 옵션으로 클라이언트 생성, 엔드포인트 선택 및 기능 검증을 제어합니다.

옵션	목적
apiKey	공급자가 자체 OpenAI 클라이언트를 생성할 때 사용하는 API 키입니다. 기본값은 SDK 전역 OpenAI 키입니다.
baseURL	OpenAI 호환 엔드포인트의 HTTP 기본 URL입니다. openAIClient와 함께 사용할 수 없습니다.
websocketBaseURL	Responses WebSocket 전송의 WebSocket 기본 URL입니다. openAIClient와 함께 사용할 수 없습니다.
openAIClient	openai 7.2 이상에서 사전 설정된 클라이언트입니다. apiKey, baseURL 또는 websocketBaseURL과 함께 사용할 수 없습니다.
organization / project	공급자가 자체 OpenAI 클라이언트를 생성할 때 전달하는 조직 및 프로젝트 값입니다.
useResponses	이 공급자가 해석한 문자열 모델 이름에 Responses API(true) 또는 Chat Completions API(false)를 선택합니다. 기본값은 프로세스 전역 setOpenAIAPI(...) 설정입니다.
useResponsesWebSocket	이 공급자가 해석한 Responses 모델에 WebSocket 전송을 사용합니다. 기본값은 프로세스 전역 setOpenAIResponsesTransport(...) 설정입니다.
cacheResponsesWebSocketModels	연결을 재사용할 수 있도록 WebSocket 기반 Responses 모델 래퍼를 재사용합니다. 기본값은 true이며, 종료 시 provider.close()를 호출하여 캐시된 래퍼를 닫습니다.
responsesWebSocketOptions	pingIntervalMs와 pingTimeoutMs를 사용해 클라이언트 연결 유지 기능을 설정합니다.
strictFeatureValidation	Chat Completions 모델에서 previousResponseId, conversationId, prompt, 어시스턴트 메시지 단계와 같은 Responses 전용 기능에 대해 UserError를 발생시킵니다. 기본적으로 이러한 기능은 경고 후 무시됩니다.

Responses 어시스턴트 메시지에 commentary 또는 final_answer의 phase가 포함되어 있으면 SDK는 이를 기록 항목의 최상위 필드로 보존합니다. 이 단계는 OpenAIConversationsSession을 통한 세션 재생과 직렬화된 RunState에서도 유지됩니다. Chat Completions에는 이에 상응하는 필드가 없으므로 기본적으로 경고 후 해당 단계를 삭제합니다. 대신 변환을 거부하려면 strictFeatureValidation: true를 설정하세요.

Chat Completions 오디오

오디오를 지원하는 Chat Completions 모델은 modelSettings.providerData를 통해 엔드포인트별 modalities 및 audio 요청 필드를 받습니다. 오디오 지원 모델을 사용하고 지원되는 요청 값은 공식 오디오 및 음성 가이드를 따르세요.

비스트리밍 호출과 스트리밍 호출 모두 오디오 전용 어시스턴트 출력을 보존합니다. 정규화된 ModelResponse.output에는 audio 콘텐츠 부분이 포함됩니다. 해당 메시지가 실행 항목이 되면 RunMessageOutputItem.rawItem에도 같은 부분이 포함됩니다. 이 항목의 audio 필드에는 base64 데이터가 포함되며, providerData에는 id, transcript, format, expires_at 같은 공급자 메타데이터가 유지됩니다. 동일한 선택 항목에 텍스트나 거부도 포함되어 있으면 정규화된 어시스턴트 메시지에 해당 텍스트나 거부가 유지됩니다. 비스트리밍 호출에서는 오디오를 포함한 전체 공급자 응답을 result.rawResponses[].providerData에서 계속 사용할 수 있습니다. 스트리밍 호출에서는 원문 모델 스트림 이벤트에서 수신되는 Chat Completions 청크를 처리하세요. 재구성된 오디오는 트레이싱용으로 보존되며 result.rawResponses에는 포함되지 않습니다. Null 오디오 조각은 무시됩니다. 형식이 잘못되었거나 복제할 수 없는 오디오 델타 또는 오디오 데이터 없이 종료되는 스트림은 ModelBehaviorError로 실패합니다. toTextStream()은 어시스턴트 텍스트만 내보냅니다. 애플리케이션에 지연 시간이 짧은 양방향 오디오가 필요한 경우에는 대신 실시간 에이전트 개요를 사용하세요.

Responses WebSocket 전송

Responses API와 함께 OpenAI 공급자를 사용하는 경우 기본 HTTP 전송 대신 WebSocket 전송을 통해 요청을 보낼 수 있습니다.

setOpenAIResponsesTransport('websocket')으로 전역에서 활성화하거나 new OpenAIProvider({ useResponses: true, useResponsesWebSocket: true })로 공급자별로 활성화합니다.

WebSocket 전송만 사용하려고 withResponsesWebSocketSession(...)이나 사용자 지정 OpenAIProvider가 필요한 것은 아닙니다. 각 실행 또는 요청마다 다시 연결해도 괜찮다면 setOpenAIResponsesTransport('websocket')을 활성화한 후에도 기존 run() / Runner.run() 사용 방식이 계속 작동합니다.

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

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

연결 재사용을 최적화하고 WebSocket 공급자 수명 주기를 더 명시적으로 관리하려는 경우에만 withResponsesWebSocketSession(...) 또는 사용자 지정 OpenAIProvider / Runner를 사용하세요.

• withResponsesWebSocketSession(...): 콜백 후 자동으로 정리되는 편리한 범위 지정 수명 주기
• 사용자 지정 OpenAIProvider / Runner: 자체 애플리케이션 아키텍처에서 명시적인 수명 주기 제어(종료 정리 포함)

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

WebSocket 프록시 또는 게이트웨이를 사용하는 경우 OpenAIProvider에서 websocketBaseURL을 설정하거나 OPENAI_WEBSOCKET_BASE_URL을 설정하세요.

responsesWebSocketOptions에서 pingIntervalMs는 클라이언트 ping 사이의 간격을 설정합니다. ping을 비활성화하려면 생략하거나 null로 설정하세요. pingTimeoutMs는 소켓을 종료하거나 닫기 전에 pong을 기다리는 시간을 설정합니다. ping은 활성화된 상태로 유지하면서 하트비트 시간 제한을 비활성화하려면 생략하거나 null로 설정하세요. 연결 유지 기능을 사용하려면 ping과 pong을 지원하는 WebSocket 구현이 필요합니다.

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

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

Responses 전용 지연 도구 로딩

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

도구 검색은 Responses API에서 이를 지원하는 GPT-5.6 Sol 및 이후 출시 모델에서만 지원됩니다.

실행에 지연 도구가 포함된 경우 같은 에이전트에 toolSearchTool()을 추가하고 modelSettings.toolChoice를 'auto'로 유지하세요. 모델이 해당 정의를 언제 로드할지 결정해야 하므로 SDK에서는 기본 제공 tool_search 도구 또는 지연 함수 도구를 이름으로 강제할 수 없습니다. 전체 설정은 도구와 공식 OpenAI 도구 검색 가이드를 참고하세요.

호스티드 멀티 에이전트(실험적)

실험적 베타

호스티드 멀티 에이전트는 베타 Responses API 항목 스키마를 사용하며 실험적 @openai/agents-openai/experimental/hosted-multi-agent 내보내기를 통해서만 사용할 수 있습니다. API와 SDK 인터페이스는 변경될 수 있습니다.

예제에서 두 패키지를 모두 직접 가져오므로 공급자 패키지와 OpenAI 클라이언트를 직접 종속성으로 설치하세요.

npm install @openai/agents-openai openai

호스티드 멀티 에이전트를 사용하면 GPT-5.6 모델이 Responses API를 통해 하위 에이전트 트리를 생성하고 조정할 수 있습니다. 이는 SDK 핸드오프 및 agents-as-tools와 다릅니다. 애플리케이션은 호스티드 하위 에이전트에 대한 로컬 Agent 객체를 생성하거나 작업을 예약하지 않습니다. 호스티드 루트 에이전트가 작업을 위임하고, 서비스가 하위 에이전트를 조정하며, /root가 최종 답변을 종합합니다. 베타 API 동작과 지원 모델은 공식 멀티 에이전트 가이드를 참고하세요.

실험적 모델 설정

OpenAIHostedMultiAgentModel을 명시적으로 생성하고 SDK Agent에 전달하세요. 모델 생성 자체가 옵트인 방식이며 별도의 활성화 플래그는 없습니다.

실험적 모델은 영구 Responses WebSocket을 사용합니다. 로컬 함수 출력은 response.inject를 통해 활성 호스티드 응답에 주입되므로 전체 실행 동안 동일한 모델 인스턴스를 유지하고 더 이상 필요하지 않을 때 닫으세요.

호스티드 멀티 에이전트 워크플로 실행

import OpenAI from 'openai';
import { Agent, run, tool } from '@openai/agents';
import {
  OpenAIHostedMultiAgentModel,
  getHostedAgentMetadata,
} from '@openai/agents-openai/experimental/hosted-multi-agent';
import { z } from 'zod';

const lookupProject = tool({
  name: 'lookup_project',
  description: 'Return details about a project.',
  parameters: z.object({ project: z.string() }),
  execute: async ({ project }, _context, details) => {
    const caller = getHostedAgentMetadata(details);
    console.log(`Tool called by ${caller?.agentName ?? 'unknown'}`);
    return { project, status: 'on track' };
  },
});

const model = new OpenAIHostedMultiAgentModel(new OpenAI(), 'gpt-5.6-sol', {
  maxConcurrentSubagents: 3,
});

try {
  const agent = new Agent({
    name: 'Hosted coordinator',
    model,
    tools: [lookupProject],
    instructions:
      'Delegate project research to hosted subagents, wait for them, and synthesize the result.',
  });

  const result = await run(agent, 'Compare projects alpha and beta.');
  console.log(result.finalOutput);
} finally {
  await model.close();
}

호스티드 협업 레코드와 하위 에이전트 메시지를 포함한 스트리밍 관측 가능성은 전체 예제를 참고하세요.

서비스 기본값인 현재 세 개를 유지하려면 maxConcurrentSubagents를 생략하세요. 값을 제공할 경우 양의 정수여야 합니다.

도구 실행 및 귀속

모든 호스티드 에이전트는 요청의 모델을 사용하며 동일한 로컬 도구 정의를 확인합니다. 호스티드 에이전트가 일반 function_call을 내보내면 기존 Agents SDK 러너가 애플리케이션 도구를 실행합니다. Responses API의 호출 ID는 라우팅 토큰입니다. SDK는 이를 요청한 호출자의 활성 호스티드 응답에 일치하는 function_call_output을 주입합니다.

getHostedAgentMetadata(details)는 도구 콜백의 세 번째 인수에서 호스티드 에이전트 이름을 읽습니다. 이 메타데이터는 로그와 애플리케이션 권한 부여에 유용하지만 라우팅을 제어하지는 않습니다. 함수 결과를 에이전트 이름으로 디스패치하지 말고 호출 ID를 보존하여 사용하세요.

도구 인수는 WebSocket을 통해 서비스에서 전달되며 도구 출력은 활성 호스티드 응답에 다시 주입됩니다. 민감한 데이터 정책, 도구 권한 부여 및 승인 검사는 애플리케이션에서 유지하세요. 도구에 부작용이 있는 경우 인터럽션된 연속 실행으로 인해 해당 효과가 반복되지 않도록 호출 ID를 기준으로 멱등성을 갖게 만드세요.

출력 및 스트리밍 동작

단계가 final_answer인 /root 메시지만 일반 어시스턴트 출력이 되어 finalOutput에 반영됩니다. 함수 호출은 러너가 실행할 수 있도록 일반 SDK 도구 호출로 유지되며, 추론 및 호스티드 툴 호출과 같은 안정적인 Responses 항목은 기존 SDK 표현을 유지합니다. 하위 에이전트 메시지, 루트 해설 및 호스티드 협업 레코드는 활성 WebSocket 응답에 남으며 SDK 기록에는 추가되지 않습니다.

호스티드 레코드와 하위 에이전트 메시지를 포함한 원문 스트리밍 이벤트는 raw_model_stream_event를 통해 계속 사용할 수 있습니다. 상위 수준 항목 스트리밍은 베타 전용 협업 레코드를 필터링하면서 안정적인 Responses 항목을 유지하며, 상위 수준 텍스트 스트리밍에는 루트의 최종 답변만 포함됩니다. 이를 통해 RunState와 세션 기록은 공급자 중립적으로 유지하면서 관측 가능성을 위해 전체 호스티드 이벤트 스트림을 보존합니다.

스트리밍된 실행은 종료 이벤트까지 처리하세요. 스트림 소비자가 조기에 중지하면 SDK는 WebSocket을 닫고 활성 호스티드 응답을 포기합니다. 이후 실행은 포기한 응답을 재개하지 않고 새로운 호스티드 응답을 시작합니다.

현재 제한 사항

실험적 SDK 모델은 Responses WebSocket 전송만 지원합니다. 베타 Responses API는 HTTP를 통한 호스티드 멀티 에이전트도 지원하지만, OpenAIHostedMultiAgentModel은 SDK 러너가 계속 진행하기 전에 각 로컬 함수 출력을 활성 응답에 주입할 수 있도록 하나의 WebSocket을 열린 상태로 유지합니다.

진행 중인 호스티드 응답의 연속 실행 상태는 OpenAIHostedMultiAgentModel 인스턴스에 보관됩니다. 모델은 대기 중인 함수 출력을 주입하기 전에 닫힌 WebSocket에 다시 연결할 수 있지만, 승인 및 인터럽션된 도구는 동일한 모델 인스턴스와 동일한 WebSocket 전송 헤더 및 쿼리로 재개해야 합니다. 모델을 다시 생성하면 연속 실행 상태가 손실됩니다. 또한 하나의 모델 인스턴스는 한 번에 하나의 활성 실행만 지원합니다.

SDK가 요청 프레임이 전송되지 않았다는 것을 알고 있는 경우에만 전송 실패를 안전하게 재생할 수 있습니다. 서버가 프레임을 수신했을 가능성이 생기면 SDK는 오류를 재생하기에 안전하지 않은 것으로 표시하고 호스티드 턴을 자동으로 반복하지 않습니다. 일반적인 재시도 정책은 모델 재시도를 참고하세요.

이 모델을 SDK 핸드오프, reasoning.summary 또는 max_tool_calls와 함께 사용하지 마세요. 이러한 조합은 요청을 보내기 전에 실패합니다. modelSettings.contextManagement로 설정한 서버 측 압축 임계값은 계속 지원되지만 Responses 압축 엔드포인트에 대한 명시적 호출은 이 모델의 수명 주기에 포함되지 않습니다. 안정적인 OpenAIResponsesModel에서는 SDK 핸드오프와 agents-as-tools를 계속 사용할 수 있습니다.

---

모델 동작 및 프롬프트

ModelSettings

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

필드	유형	참고
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	응답의 최대 토큰 수입니다.
timeoutMs	number	각 모델 요청 시도의 협력적 시간 제한(밀리초)입니다. 유한한 값이어야 하며 0보다 크고 2147483647 이하여야 합니다.
store	boolean	검색 또는 RAG 워크플로를 위해 응답을 보존합니다.
promptCacheRetention	'in-memory' | '24h' | null	지원되는 경우 기존 최대 프롬프트 캐시 보존 정책을 제어합니다. 이는 promptCacheOptions.ttl과 별개입니다.
promptCacheOptions	{ mode?: 'implicit' | 'explicit'; ttl?: '30m' }	GPT-5.6 이상 모델에서 암시적 또는 명시적 프롬프트 캐시 중단점을 제어합니다.
contextManagement	ModelSettingsContextManagement	서버 측 압축과 같은 공급자 컨텍스트 관리를 제어합니다.
reasoning.effort	'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'	지원되는 gpt-5.x 모델의 추론 노력입니다. max는 GPT-5.6에서 지원됩니다.
reasoning.mode	'standard' | 'pro' | string	추론 실행 모드를 선택합니다. 이 설정에는 Responses API가 필요합니다.
reasoning.context	'auto' | 'current_turn' | 'all_turns' | null	이후 턴에서 모델에 다시 렌더링할 추론 항목을 제어합니다. 이 설정에는 Responses API가 필요합니다.
reasoning.summary	'auto' | 'concise' | 'detailed'	모델이 반환하는 추론 요약의 양을 제어합니다.
text.verbosity	'low' | 'medium' | 'high'	gpt-5.x 등의 텍스트 상세 수준입니다.
providerData	Record<string, any>	기반 모델로 전달되는 공급자별 패스스루 옵션입니다.
preserveRawUsage	boolean	완료된 각 모델 응답에서 SDK 정규화 전의 공급자 사용량에 대한 분리된 JSON 호환 스냅샷을 보존합니다. 기본적으로 비활성화되어 있습니다.
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 수준 설정은 충돌하는 에이전트별 설정보다 우선합니다. reasoning, text, promptCacheOptions, retry의 중첩 필드는 undefined로 상속된 값을 명시적으로 제거하지 않는 한 러너와 에이전트 설정 간에 병합됩니다.

timeoutMs가 만료되면 SDK는 현재 모델 요청 시도를 중단합니다. 재시도 처리에서 다른 시도를 시작하지도, 다른 실패를 노출하지도 않으면 SDK는 ModelTimeoutError를 발생시킵니다. 실행 수준 중단 신호는 여전히 전체 실행을 취소합니다. 모델 재시도가 활성화되어 있으면 재시도 정책은 시간 제한을 또 다른 실패 시도처럼 평가합니다. 해당 정책이 재시도를 선택하고 요청을 안전하게 재생할 수 있거나 애플리케이션이 안전하지 않은 재생을 명시적으로 승인한 경우에만 SDK가 재시도합니다.

공급자별 사용량 필드가 필요하거나 생략된 필드와 정규화된 0을 구분해야 할 때 preserveRawUsage: true를 설정하세요. OpenAI Responses, OpenAI Chat Completions 및 AI SDK 기반 모델은 스트리밍 및 비스트리밍 실행에서 이를 지원합니다. 보존은 최선형 방식으로 수행됩니다. 공급자가 사용량을 반환하지 않거나 일반 JSON 호환 데이터로 안전하게 복사할 수 없는 값을 반환하면 rawUsage는 undefined로 유지됩니다. 보존된 페이로드에 접근하는 방법은 원문 응답을 참고하세요.

GPT-5.6 추론 및 프롬프트 캐시 제어

GPT-5.6에는 요청 수준 추론 모드와 명시적 프롬프트 캐시 중단점이 추가되었습니다. reasoning.mode와 reasoning.context는 Responses 전용 설정입니다. OpenAIChatCompletionsModel은 한 번 경고한 후 이를 무시하거나, 엄격한 기능 검증이 활성화된 경우 요청 전에 UserError를 발생시킵니다. reasoning.effort는 지원되는 Chat Completions 모델에서 계속 사용할 수 있습니다.

promptCacheOptions는 Responses 및 Chat Completions 모델 경로 모두에서 전달됩니다. 기본 implicit 모드에서는 OpenAI가 명시적 중단점 외에 자동 중단점을 선택할 수 있습니다. promptCacheBreakpoint: { mode: 'explicit' }로 표시된 콘텐츠 부분만 사용하려면 mode: 'explicit'를 설정하세요. 현재 지원되는 최소 캐시 수명은 30m입니다.

GPT-5.6 요청 제어 설정

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

const agent = new Agent({
  name: 'Research assistant',
  model: 'gpt-5.6',
  modelSettings: {
    reasoning: {
      mode: 'pro',
      effort: 'max',
      context: 'all_turns',
    },
    promptCacheOptions: {
      mode: 'explicit',
      ttl: '30m',
    },
  },
});

await run(agent, [
  {
    role: 'user',
    content: [
      {
        type: 'input_text',
        text: 'Treat this research brief as a reusable prompt prefix.',
        promptCacheBreakpoint: { mode: 'explicit' },
      },
      {
        type: 'input_text',
        text: 'Summarize the brief and identify its main risks.',
      },
    ],
  },
]);

명시적 중단점은 GPT-5.6 이상 모델에서 지원됩니다. 지원되는 콘텐츠 부분 유형과 중단점 제한은 API에 따라 다릅니다. 최신 세부 정보는 공식 프롬프트 캐시 중단점 가이드를 참고하세요.

모델 재시도

재시도는 런타임 전용이며 옵트인 방식입니다. 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를 반환하지 않고 재시도할 때의 기본 지연 전략입니다. backoff.maxDelayMs는 계산된 백오프 지연만 제한하며, 정책이 반환한 명시적 delayMs 값이나 retry-after 힌트는 제한하지 않습니다.
policy	RetryPolicy	재시도 여부를 결정하는 콜백입니다. 이 함수는 런타임 전용이며 지속 실행 상태에 직렬화되지 않습니다.

재시도 정책은 다음 정보를 포함하는 RetryPolicyContext를 받습니다.

• 시도 횟수에 따라 결정할 수 있도록 attempt와 maxRetries
• 스트리밍 동작과 비스트리밍 동작을 구분할 수 있도록 stream
• 원문 검사를 위한 error
• statusCode, retryAfterMs, errorCode, isNetworkError, isAbort 같은 정규화된 정보
• 기반 모델 또는 공급자가 재시도 지침을 제공할 수 있는 경우 providerAdvice
• 애플리케이션 정책이 공급자별 오류를 재해석하지 않고 러너의 안정적인 재생 분류를 검사할 수 있도록 replaySafety, responseStarted, statefulRequest

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

• 간단한 재시도 결정을 위한 true / false
• 지연 시간을 재정의하거나, 로깅용 진단 사유를 추가하거나, 공급자가 안전하지 않은 것으로 표시한 비스트리밍 재생을 명시적으로 승인하려는 경우 { retry, delayMs?, reason?, approveUnsafeReplay? }

SDK는 retryPolicies에 즉시 사용할 수 있는 도우미를 제공합니다.

도우미	동작
retryPolicies.never()	항상 재시도하지 않습니다.
retryPolicies.providerSuggested()	가능한 경우 공급자의 재시도 지침을 따릅니다.
retryPolicies.networkError()	일시적인 전송 또는 연결 실패와 일치합니다.
retryPolicies.httpStatus([..])	선택한 HTTP 상태 코드와 일치합니다.
retryPolicies.retryAfter()	retry-after 힌트가 있을 때만 재시도하며, 해당 힌트를 backoff.maxDelayMs로 제한되지 않는 명시적 지연 시간으로 사용합니다.
retryPolicies.any(...)	중첩된 정책 중 하나라도 재시도를 선택하면 재시도합니다.
retryPolicies.all(...)	중첩된 모든 정책이 재시도를 선택할 때만 재시도합니다.

정책을 조합할 때는 공급자가 거부 및 재생 안전성 승인을 구분할 수 있는 경우 이를 보존하므로 providerSuggested()가 가장 안전한 첫 번째 기본 구성 요소입니다.

안전 경계

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

• 중단 오류
• 표시되는 이벤트 또는 원문 모델 이벤트가 이미 내보내진 이후의 스트리밍 실행
• 재생이 안전하지 않다고 표시하는 공급자 지침

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

애플리케이션은 { retry: true, approveUnsafeReplay: true }를 반환하여 비스트리밍 요청에 대한 공급자의 안전하지 않음 분류를 재정의할 수 있습니다. 이는 이전 요청이 이미 수락되었을 수 있으며 재시도 시 응답이나 기타 공급자 측 작업이 중복될 수 있음을 명시적으로 인정하는 것입니다. 애플리케이션에서 이러한 결과를 감당할 수 있을 때만 사용하세요. 중단 처리, 이벤트를 내보낸 스트리밍 요청 또는 안전하지 않은 스트리밍 재생은 재정의하지 않습니다. retryPolicies.any(...) 또는 retryPolicies.all(...)로 정책을 조합하면 반환된 결정에서 approveUnsafeReplay: true를 명시적으로 설정한 경우에만 승인이 유지됩니다.

러너 및 에이전트 병합 동작

retry는 러너 수준 및 에이전트 수준 modelSettings 간에 깊은 병합됩니다.

• 에이전트는 retry.maxRetries만 재정의하면서 러너의 policy를 계속 상속할 수 있습니다.
• 에이전트는 retry.backoff의 일부만 재정의하면서 러너의 다른 백오프 필드를 유지할 수 있습니다.
• 상속된 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);
});

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

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

---

고급 공급자 및 관측 가능성

사용자 지정 모델 공급자

자체 공급자를 구현하는 방법은 간단합니다. 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);

모든 run() 호출과 새로 생성되는 모든 Runner에서 기본적으로 같은 공급자를 사용하려면 애플리케이션 시작 시 한 번 설정하세요.

기본 모델 공급자 설정

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

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

애플리케이션에서 OpenAI 이외의 공급자를 표준으로 사용하며 모든 곳에 사용자 지정 Runner를 전달하고 싶지 않을 때 유용합니다.

AI SDK 연동

직접 ModelProvider를 구현하지 않고 OpenAI 이외의 모델을 사용하려면 Vercel AI SDK로 모든 모델 사용을 참고하세요. 이 어댑터를 사용하면 AI SDK 모델을 Agents 런타임에 직접 연결할 수 있습니다. 애플리케이션에서 이미 AI SDK 공급자를 표준으로 사용하거나 더 폭넓은 공급자 생태계에 접근하려는 경우 유용합니다. 또한 Agents SDK providerData가 AI SDK providerMetadata에 매핑되는 방식과 AI SDK UI 라우트에서 사용할 수 있는 스트림 도우미도 설명합니다.

---

트레이싱 자격 증명

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

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

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

setTracingExportApiKey('sk-...');

이 자격 증명을 사용하여 OpenAI 대시보드로 트레이스를 전송합니다. 사용자 지정 수집 엔드포인트 또는 재시도 조정 같은 내보내기 도구 사용자 지정은 트레이싱을 참고하세요.

---

다음 단계

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