모델
모든 에이전트는 궁극적으로 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 환경 변수를 설정하세요.
export OPENAI_DEFAULT_MODEL=gpt-5node my-awesome-agent.js둘째, Runner 인스턴스에 기본 모델을 설정할 수 있습니다. 에이전트에 모델을 설정하지 않으면 이 Runner의 기본 모델이 사용됩니다.
import { Runner } from '@openai/agents';
const runner = new Runner({ model: 'gpt‑4.1-mini' });GPT-5 모델
섹션 제목: “GPT-5 모델”이 방식으로 GPT-5의 추론 모델(gpt-5, gpt-5-mini, gpt-5-nano)을 사용할 때, SDK는 합리적인 기본 modelSettings를 적용합니다. 구체적으로 reasoning.effort와 verbosity를 모두 "low"로 설정합니다. 기본 모델의 추론 강도를 조정하려면 직접 modelSettings를 전달하세요:
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-nano를 reasoning.effort="minimal"과 함께 사용하면 기본 설정보다 더 빠르게 응답을 반환하는 경우가 많습니다. 다만 Responses API의 일부 내장 도구(예: 파일 검색과 이미지 생성)는 "minimal" 추론 강도를 지원하지 않으므로, 이 Agents SDK의 기본값은 "low"입니다.
비 GPT-5 모델
섹션 제목: “비 GPT-5 모델”사용자 지정 modelSettings 없이 비 GPT-5 모델 이름을 전달하면, SDK는 모든 모델과 호환되는 일반적인 modelSettings로 되돌립니다.
OpenAI 프로바이더
섹션 제목: “OpenAI 프로바이더”기본 ModelProvider는 OpenAI API를 사용하여 이름을 해석합니다. 두 가지 구분된 엔드포인트를 지원합니다:
| API | 사용처 | setOpenAIAPI() 호출 |
|---|---|---|
| Chat Completions | 표준 채팅 및 함수 호출 | setOpenAIAPI('chat_completions') |
| Responses | 스트리밍 우선의 새로운 생성 API(툴 호출, 유연한 출력) | setOpenAIAPI('responses') (default) |
import { setDefaultOpenAIKey } from '@openai/agents';
setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...네트워킹 설정을 커스터마이즈해야 하는 경우 setDefaultOpenAIClient(client)를 통해 직접 OpenAI 클라이언트를 연결할 수도 있습니다.
ModelSettings
섹션 제목: “ModelSettings”ModelSettings는 OpenAI 매개변수를 반영하지만 공급자에 구애받지 않습니다.
| 필드 | 타입 | 비고 |
|---|---|---|
temperature | number | 창의성 대 결정론 |
topP | number | 누클리어스 샘플링 |
frequencyPenalty | number | 반복 토큰에 패널티 부여 |
presencePenalty | number | 새로운 토큰 장려 |
toolChoice | 'auto' | 'required' | 'none' | string | 강제 도구 사용 참고 |
parallelToolCalls | boolean | 지원되는 경우 병렬 함수 호출 허용 |
truncation | 'auto' | 'disabled' | 토큰 절단 전략 |
maxTokens | number | 응답의 최대 토큰 수 |
store | boolean | 검색 / RAG 워크플로를 위해 응답을 영속화 |
reasoning.effort | 'minimal' | 'low' | 'medium' | 'high' | gpt-5 등에서의 추론 강도 |
text.verbosity | 'low' | 'medium' | 'high' | gpt-5 등에서의 텍스트 상세 수준 |
설정은 어느 레벨이든 부착할 수 있습니다:
import { Runner, Agent } from '@openai/agents';
const agent = new Agent({ name: 'Creative writer', // ... modelSettings: { temperature: 0.7, toolChoice: 'auto' },});
// or globallynew Runner({ modelSettings: { temperature: 0.3 } });Runner 수준의 설정은 에이전트별 설정과 충돌 시 우선합니다.
프롬프트
섹션 제목: “프롬프트”에이전트는 prompt 매개변수로 구성할 수 있으며, 이는 에이전트의 동작을 제어하기 위해 서버에 저장된 프롬프트 구성을 사용해야 함을 나타냅니다. 현재 이 옵션은 OpenAI Responses API를 사용할 때만 지원됩니다.
| 필드 | 타입 | 비고 |
|---|---|---|
promptId | string | 프롬프트의 고유 식별자 |
version | string | 사용하려는 프롬프트의 버전 |
variables | object | 프롬프트에 치환할 변수의 키/값 쌍. 값은 문자열 또는 텍스트, 이미지, 파일 등의 콘텐츠 입력 타입일 수 있음 |
import { Agent, run } from '@openai/agents';
async function main() { const agent = new Agent({ name: 'Assistant', prompt: { promptId: 'pmpt_68d50b26524c81958c1425070180b5e10ab840669e470fc7', variables: { name: 'Kaz' }, }, });
const result = await run(agent, 'What is your name?'); console.log(result.finalOutput);}
main().catch((error) => { console.error(error); process.exit(1);});tools 또는 instructions와 같은 추가 에이전트 구성은 저장된 프롬프트에 구성했을 수 있는 값을 재정의합니다.
사용자 정의 모델 프로바이더
섹션 제목: “사용자 정의 모델 프로바이더”직접 프로바이더를 구현하는 것은 간단합니다 – 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);트레이싱 익스포터
섹션 제목: “트레이싱 익스포터”OpenAI 프로바이더를 사용할 때 API 키를 제공하여 자동 트레이스 내보내기를 옵트인할 수 있습니다:
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');이는 OpenAI 대시보드로 트레이스를 전송하며, 워크플로의 전체 실행 그래프를 확인할 수 있습니다.