콘텐츠로 이동

모델

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

  • Model – 특정 API에 대해 하나의 요청을 수행하는 방법을 알고 있습니다
  • ModelProvider – 사람이 읽을 수 있는 모델 이름(예: 'gpt‑4o')을 Model 인스턴스로 해석합니다

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

에이전트별 모델 지정
import { Agent } from '@openai/agents';
const agent = new Agent({
name: 'Creative writer',
model: 'gpt-4.1',
});

Agent를 초기화할 때 모델을 지정하지 않으면 기본 모델이 사용됩니다. 현재 기본값은 에이전트 워크플로의 예측 가능성과 낮은 지연 시간의 균형이 좋은 gpt-4.1입니다.

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

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

Terminal window
export OPENAI_DEFAULT_MODEL=gpt-5
node my-awesome-agent.js

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

Runner에 기본 모델 설정
import { Runner } from '@openai/agents';
const runner = new Runner({ model: 'gpt‑4.1-mini' });

이 방식으로 GPT-5의 reasoning 모델(gpt-5, gpt-5-mini, gpt-5-nano)을 사용할 때, SDK는 합리적인 기본 modelSettings를 적용합니다. 구체적으로 reasoning.effortverbosity를 모두 "low"로 설정합니다. 기본 모델의 reasoning effort를 조정하려면 사용자 지정 modelSettings를 전달하세요:

GPT-5 기본 설정 사용자 지정
import { Agent } from '@openai/agents';
const myAgent = new Agent({
name: 'My Agent',
instructions: "You're a helpful agent.",
modelSettings: {
reasoning: { effort: 'minimal' },
text: { verbosity: 'low' },
},
// If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only modelSettings works.
// It's also fine to pass a GPT-5 model name explicitly:
// model: 'gpt-5',
});

더 낮은 지연 시간을 위해 gpt-5-mini 또는 gpt-5-nanoreasoning.effort="minimal"과 함께 사용하면 기본 설정보다 빠르게 응답하는 경우가 많습니다. 다만 Responses API의 일부 내장 도구(예: 파일 검색 및 이미지 생성)는 "minimal" reasoning effort를 지원하지 않으므로, 이 Agents SDK는 기본값을 "low"로 둡니다.

커스텀 modelSettings 없이 비 GPT-5 모델 이름을 전달하면, SDK는 모든 모델과 호환되는 일반 modelSettings로 되돌립니다.


기본 ModelProvider는 OpenAI API를 사용하여 이름을 해석합니다. 두 가지 별도의 엔드포인트를 지원합니다:

API사용setOpenAIAPI() 호출
Chat Completions표준 채팅 및 함수 호출setOpenAIAPI('chat_completions')
Responses새로운 스트리밍 우선 생성 API(도구 호출, 유연한 출력)setOpenAIAPI('responses') (default)
기본 OpenAI 키 설정
import { setDefaultOpenAIKey } from '@openai/agents';
setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

네트워킹 설정을 커스터마이즈해야 하는 경우 setDefaultOpenAIClient(client)를 통해 자체 OpenAI 클라이언트를 연결할 수도 있습니다.


ModelSettings는 OpenAI 매개변수를 반영하지만 제공자에 구애받지 않습니다.

필드타입비고
temperaturenumber창의성 대 결정성
topPnumber누클리어스 샘플링
frequencyPenaltynumber반복 토큰 페널티
presencePenaltynumber새로운 토큰 장려
toolChoice'auto' | 'required' | 'none' | string도구 사용 강제 참고
parallelToolCallsboolean지원되는 곳에서 병렬 함수 호출 허용
truncation'auto' | 'disabled'토큰 절단 전략
maxTokensnumber응답의 최대 토큰 수
storeboolean검색 / RAG 워크플로를 위해 응답을 저장
reasoning.effort'minimal' | 'low' | 'medium' | 'high'gpt-5 등에서의 reasoning effort
text.verbosity'low' | 'medium' | 'high'gpt-5 등에서의 텍스트 verbosity

설정은 두 수준 중 어느 곳에도 연결할 수 있습니다:

모델 설정
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를 사용할 때만 지원됩니다.

필드타입비고
promptIdstring프롬프트의 고유 식별자
versionstring사용하려는 프롬프트의 버전
variablesobject프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열 또는 텍스트, 이미지, 파일 같은 콘텐츠 입력 타입이 될 수 있습니다
프롬프트가 있는 에이전트
import { Agent, run } from '@openai/agents';
async function main() {
const agent = new Agent({
name: 'Assistant',
prompt: {
promptId: 'pmpt_684b3b772e648193b92404d7d0101d8a07f7a7903e519946',
version: '1',
variables: {
poem_style: 'limerick',
},
},
});
const result = await run(agent, 'Write about unrequited love.');
console.log(result.finalOutput);
}
if (require.main === module) {
main().catch(console.error);
}

tools 또는 instructions와 같은 추가 에이전트 구성은 저장된 프롬프트에 구성해 둔 값을 재정의합니다.


자체 제공자를 구현하는 것은 간단합니다 – ModelProviderModel을 구현하고 제공자를 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 프로바이더를 사용할 때 API 키를 제공하여 자동 트레이스 내보내기를 옵트인할 수 있습니다:

트레이싱 익스포터
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');

이는 트레이스를 OpenAI 대시보드로 전송하며, 워크플로의 전체 실행 그래프를 확인할 수 있습니다.