콘텐츠로 이동

모델

모든 에이전트는 궁극적으로 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를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 gpt-5.6-luna이며, 대용량 에이전트 워크로드를 효율적으로 처리하도록 reasoning.effort: "none"과 text.verbosity: "low"가 설정되어 있습니다.

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.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"을 사용한 다음, 작업에 더 신중한 추론이 필요한 경우에만 추론 강도를 높이세요.

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


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

apiKey, baseURL, organization, project 중 하나라도 있으면 해당 OpenAIProvider는 setDefaultOpenAIClient(...)로 설정한 클라이언트를 재사용하지 않고 프로바이더별 값으로 자체 OpenAI 클라이언트를 생성합니다. 이러한 옵션과 openAIClient가 모두 없으면 프로바이더는 SDK 전역 기본 클라이언트를 재사용할 수 있습니다. websocketBaseURL은 Responses WebSocket 연결 대상을 변경하지만, 이 옵션만으로 HTTP 클라이언트가 교체되지는 않습니다.

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

Responses 스트리밍 프로토콜은 타입이 지정된 종료 이벤트를 사용합니다. SDK는 응답 페이로드가 있는 response.completed 이벤트를 성공적인 모델 결과로 처리합니다. failed 또는 incomplete 응답, response.failed, response.incomplete, response.error 이벤트, error 이벤트, 또는 필수 응답 페이로드가 없는 response.completed 이벤트는 스트리밍 실행과 비스트리밍 실행 모두에서 ModelBehaviorError를 발생시킵니다.

SDK는 성공하지 못한 종료 상태를 이미 시작되었을 수 있으며 재실행하기에 안전하지 않은 응답으로 취급합니다. 비스트리밍 실행에서는 기본 재시도 권고에 따라 요청을 자동으로 반복하지 않습니다. 러너가 재시도하려면 사용자 지정 재시도 정책에서 안전하지 않은 재실행을 명시적으로 승인해야 합니다. 스트리밍 실행에서는 사용자 지정 재시도 정책이 안전하지 않은 재실행을 승인하더라도 원문 종료 이벤트를 내보낸 후에는 러너가 재시도하지 않습니다. 성공하지 못한 응답에 사용량이 보고되면 러너는 해당 사용량을 트레이싱과 실행 사용량 집계에 포함합니다. 스트리밍 결과는 result.completed가 거부되더라도 result.state.usage에 사용량을 유지합니다.

성공하지 못한 응답은 성공적인 ModelResponse가 되지 않으며, rawResponses나 세션 기록에 추가되지 않고, 해당 응답의 출력 항목도 실행되지 않습니다. 스트리밍 소비자는 result.completed가 거부되기 전에 원문 모델 이벤트 스트림을 통해 원래 종료 이벤트를 확인할 수 있습니다. 종료 시점의 부분 출력을 재생 가능한 기록이나 최종 출력으로 취급하지 마세요.

Chat Completions에서 finish_reason: 'length'는 토큰 또는 컨텍스트 한도에 도달하여 프로바이더가 생성을 중단했음을 의미합니다. 선택 항목에 유효한 텍스트, 거부 응답, 오디오, 추론 또는 함수 호출이 포함되어 있으면 SDK는 해당 어시스턴트 페이로드의 일부를 보존합니다. 잘린 선택 항목에 이러한 페이로드가 하나도 없으면 SDK는 빈 선택 항목을 성공적인 응답으로 처리하는 대신 스트리밍 실행과 비스트리밍 실행 모두에서 ModelBehaviorError를 발생시킵니다.

SDK는 이러한 빈 잘림 결과를 이미 시작되었을 수 있으며 재실행하기에 안전하지 않은 응답으로 취급합니다. 스트리밍 소비자는 result.completed가 거부되기 전에 이미 원문 청크를 받았을 수 있습니다. 실패한 시도에서 사용량이 보고되면 러너는 해당 사용량을 트레이싱과 실행 사용량 집계에 포함합니다.

오디오를 지원하는 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()은 어시스턴트 텍스트만 내보냅니다. 애플리케이션에 지연 시간이 짧은 양방향 오디오가 필요하면 대신 음성 에이전트 개요에 설명된 Realtime API를 사용하세요.

OpenAI 프로바이더를 Responses API와 함께 사용할 때 기본 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 간격을 설정합니다. 생략하거나 null로 설정하면 ping이 비활성화됩니다. pingTimeoutMs는 소켓을 종료하거나 닫기 전에 pong을 기다리는 시간을 설정합니다. 생략하거나 null로 설정하면 ping은 활성화된 상태로 유지하면서 하트비트 타임아웃을 비활성화합니다. 연결 유지를 사용하려면 ping 및 pong 지원을 제공하는 WebSocket 구현이 필요합니다.

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

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

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

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

실행에 지연 도구가 포함되어 있으면 동일한 에이전트에 toolSearchTool()을 추가하고 modelSettings.toolChoice를 'auto'로 유지하세요. 모델이 해당 정의를 로드할 시점을 결정해야 하므로 SDK는 내장 tool_search 도구나 지연 함수 도구를 이름으로 강제 지정하는 것을 허용하지 않습니다. 전체 설정 방법은 도구 가이드와 공식 OpenAI 도구 검색 가이드를 참고하세요.

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

섹션 제목: “호스티드 멀티 에이전트(실험적)”

코드 예제에서 두 패키지를 모두 직접 가져오므로 프로바이더 패키지와 OpenAI 클라이언트를 직접 의존성으로 설치하세요.

터미널 창
npm install @openai/agents-openai openai

호스티드 멀티 에이전트를 사용하면 GPT-5.6 모델이 Responses API를 통해 하위 에이전트 트리를 생성하고 조율할 수 있습니다. 이는 핸드오프 및 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();
}

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

서비스 기본값인 현재 3을 유지하려면 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는 OpenAI 매개변수를 반영하지만 특정 프로바이더에 종속되지 않습니다.

필드타입설명
temperaturenumber창의성과 결정성 간의 균형입니다.
topPnumber뉴클리어스 샘플링입니다.
frequencyPenaltynumber반복되는 토큰에 페널티를 부여합니다.
presencePenaltynumber새로운 토큰을 유도합니다.
toolChoice'auto' | 'required' | 'none' | string도구 사용 강제를 참고하세요. OpenAI Responses에서 toolChoice: 'computer'는 정식 출시(GA)된 내장 컴퓨터 도구를 사용할 수 있을 때 해당 도구 사용을 강제합니다.
parallelToolCallsboolean지원되는 경우 병렬 함수 호출을 허용합니다.
truncation'auto' | 'disabled'토큰 잘림 전략입니다.
maxTokensnumber응답의 최대 토큰 수입니다.
timeoutMsnumber각 모델 요청 시도에 대한 밀리초 단위의 협력적 타임아웃입니다. 유한한 값이어야 하며, 0보다 크고 2147483647 이하여야 합니다.
storeboolean검색 / RAG 워크플로를 위해 응답을 저장합니다.
promptCacheRetention'in-memory' | '24h' | null지원되는 경우 기존의 최대 프롬프트 캐시 보존 정책을 제어합니다. promptCacheOptions.ttl과는 독립적입니다.
promptCacheOptions{ mode?: 'implicit' | 'explicit'; ttl?: '30m' }GPT-5.6 이상 모델의 암시적 또는 명시적 프롬프트 캐시 경계점을 제어합니다.
contextManagementModelSettingsContextManagement서버 측 압축과 같은 프로바이더 컨텍스트 관리를 제어합니다.
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 등의 텍스트 상세 수준입니다.
providerDataRecord<string, any>기본 모델에 그대로 전달되는 프로바이더별 옵션입니다.
preserveRawUsageboolean완료된 각 모델 응답에서 SDK 정규화 전에 프로바이더 사용량의 독립적인 JSON 호환 스냅샷을 보존합니다. 기본적으로 비활성화되어 있습니다.
retryModelRetrySettings런타임에서만 사용되며 명시적으로 활성화하는 재시도 설정입니다. 모델 재시도를 참고하세요.

설정은 어느 수준에서든 적용할 수 있습니다.

모델 설정
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 추론 및 프롬프트 캐시 제어”

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에는 세 가지 필드가 있습니다.

필드타입설명
maxRetriesnumber최초 요청 이후 허용되는 재시도 횟수입니다.
backoff{ initialDelayMs?, maxDelayMs?, multiplier?, jitter? }정책이 delayMs를 반환하지 않고 재시도할 때 사용하는 기본 지연 전략입니다. backoff.maxDelayMs는 이 계산된 백오프 지연에만 상한을 적용하며, 정책이 반환한 명시적 delayMs 값이나 retry-after 힌트에는 상한을 적용하지 않습니다.
policyRetryPolicy재시도 여부를 결정하는 콜백입니다. 이 함수는 런타임에서만 사용되며 저장되는 실행 상태에 직렬화되지 않습니다.

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

  • 시도 횟수를 고려하여 결정할 수 있는 attempt와 maxRetries
  • 스트리밍 동작과 비스트리밍 동작을 분기할 수 있는 stream
  • 원문 검사를 위한 error
  • statusCode, retryAfterMs, errorCode, isNetworkError, isAbort와 같은 normalized 정보
  • 기본 모델/프로바이더가 재시도 지침을 제공할 수 있을 때의 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는 정적 객체이거나 런타임에 객체를 반환하는 함수일 수 있습니다. 콜백 형식은 동적 프롬프트를 참고하세요.

필드타입설명
promptIdstring프롬프트의 고유 식별자입니다.
versionstring사용할 프롬프트 버전입니다.
variablesobject프롬프트에 대입할 변수의 키/값 쌍입니다. 값은 문자열이거나 텍스트, 이미지, 파일과 같은 콘텐츠 입력 타입일 수 있습니다.
프롬프트가 있는 에이전트
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를 전달하고 싶지 않을 때 유용합니다.

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


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

트레이싱 내보내기 API 키 설정
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');

이 설정은 해당 자격 증명을 사용하여 OpenAI 대시보드로 트레이스를 보냅니다. 사용자 지정 수집 엔드포인트나 재시도 조정과 같은 내보내기 도구 사용자 지정은 트레이싱 가이드를 참고하세요.