에이전트
에이전트는 OpenAI Agents SDK의 핵심 구성 요소입니다. Agent는 다음으로 구성된 대규모 언어 모델(LLM)입니다:
- Instructions – 모델에게 자기 정체 와 응답 방식 을 알려주는 시스템 프롬프트
- Model – 호출할 OpenAI 모델과 선택적 모델 튜닝 매개변수
- Tools – LLM이 작업을 수행하기 위해 호출할 수 있는 함수 또는 API 목록
import { Agent } from '@openai/agents';
const agent = new Agent({ name: 'Haiku Agent', instructions: 'Always respond in haiku form.', model: 'gpt-5-nano', // optional – falls back to the default model});
이 페이지의 나머지 부분에서는 모든 Agent 기능을 자세히 설명합니다.
기본 구성
섹션 제목: “기본 구성”Agent
생성자는 하나의 구성 객체를 받습니다. 가장 일반적으로 사용되는 속성은 아래와 같습니다.
Property | Required | Description |
---|---|---|
name | yes | 짧은 사람이 읽을 수 있는 식별자 |
instructions | yes | 시스템 프롬프트(문자열 또는 함수 – Dynamic instructions 참고) |
model | no | 모델 이름 또는 사용자 정의 Model 구현 |
modelSettings | no | 튜닝 매개변수(temperature, top_p 등). 필요한 속성이 최상위에 없다면 providerData 아래에 포함할 수 있음 |
tools | no | 모델이 호출할 수 있는 Tool 인스턴스 배열 |
import { Agent, tool } from '@openai/agents';import { z } from 'zod';
const getWeather = tool({ name: 'get_weather', description: 'Return the weather for a given city.', parameters: z.object({ city: z.string() }), async execute({ city }) { return `The weather in ${city} is sunny.`; },});
const agent = new Agent({ name: 'Weather bot', instructions: 'You are a helpful weather bot.', model: 'gpt-4.1', tools: [getWeather],});
컨텍스트
섹션 제목: “컨텍스트”에이전트는 컨텍스트 타입에 대해 제네릭 입니다 – 즉 Agent<TContext, TOutput>
. 컨텍스트 는 여러분이 생성하여 Runner.run()
에 전달하는 의존성 주입 객체입니다. 모든 도구, 가드레일, 핸드오프 등에 전달되며, 상태 저장 또는 공유 서비스(데이터베이스 연결, user 메타데이터, 기능 플래그 등)를 제공하는 데 유용합니다.
import { Agent } from '@openai/agents';
interface Purchase { id: string; uid: string; deliveryStatus: string;}interface UserContext { uid: string; isProUser: boolean;
// this function can be used within tools fetchPurchases(): Promise<Purchase[]>;}
const agent = new Agent<UserContext>({ name: 'Personal shopper', instructions: 'Recommend products the user will love.',});
// Laterimport { run } from '@openai/agents';
const result = await run(agent, 'Find me a new pair of running shoes', { context: { uid: 'abc', isProUser: true, fetchPurchases: async () => [] },});
출력 타입
섹션 제목: “출력 타입”기본적으로 Agent는 일반 텍스트(string
)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 outputType
속성을 지정할 수 있습니다. SDK는 다음을 허용합니다:
- Zod 스키마(
z.object({...})
) - JSON‑schema 호환 객체
import { Agent } from '@openai/agents';import { z } from 'zod';
const CalendarEvent = z.object({ name: z.string(), date: z.string(), participants: z.array(z.string()),});
const extractor = new Agent({ name: 'Calendar extractor', instructions: 'Extract calendar events from the supplied text.', outputType: CalendarEvent,});
outputType
이 제공되면, SDK는 일반 텍스트 대신 자동으로 structured outputs을 사용합니다.
멀티 에이전트 시스템 설계 패턴
섹션 제목: “멀티 에이전트 시스템 설계 패턴”에이전트를 함께 구성하는 방법은 여러 가지가 있습니다. 실제 프로덕션 앱에서 자주 보이는 두 가지 패턴은 다음과 같습니다:
- 매니저(도구로서의 에이전트) – 중앙 에이전트가 대화를 소유하고 도구로 노출된 전문 에이전트를 호출함
- 핸드오프 – 초기 에이전트가 사용자의 요청을 파악하면 전체 대화를 전문가에게 위임함
이 접근 방식들은 상호 보완적입니다. 매니저는 가드레일 또는 레이트 리밋을 한 곳에서 집행할 수 있게 해주고, 핸드오프는 각 에이전트가 대화의 제어를 유지하지 않고 단일 작업에 집중할 수 있게 해줍니다.
매니저(도구로서의 에이전트)
섹션 제목: “매니저(도구로서의 에이전트)”이 패턴에서 매니저는 결코 제어를 넘기지 않습니다 — LLM이 도구를 사용하고 매니저가 최종 답변을 요약합니다. 자세한 내용은 도구를 참고하세요.
import { Agent } from '@openai/agents';
const bookingAgent = new Agent({ name: 'Booking expert', instructions: 'Answer booking questions and modify reservations.',});
const refundAgent = new Agent({ name: 'Refund expert', instructions: 'Help customers process refunds and credits.',});
const customerFacingAgent = new Agent({ name: 'Customer-facing agent', instructions: 'Talk to the user directly. When they need booking or refund help, call the matching tool.', tools: [ bookingAgent.asTool({ toolName: 'booking_expert', toolDescription: 'Handles booking questions and requests.', }), refundAgent.asTool({ toolName: 'refund_expert', toolDescription: 'Handles refund questions and requests.', }), ],});
핸드오프
섹션 제목: “핸드오프”핸드오프에서는 분류 에이전트가 요청을 라우팅하지만, 일단 핸드오프가 발생하면 전문가 에이전트가 최종 출력을 생성할 때까지 대화를 소유합니다. 이는 프롬프트를 짧게 유지하고 각 에이전트를 독립적으로 추론할 수 있게 해줍니다. 자세한 내용은 핸드오프를 참고하세요.
import { Agent } from '@openai/agents';
const bookingAgent = new Agent({ name: 'Booking Agent', instructions: 'Help users with booking requests.',});
const refundAgent = new Agent({ name: 'Refund Agent', instructions: 'Process refund requests politely and efficiently.',});
// Use Agent.create method to ensure the finalOutput type considers handoffsconst triageAgent = Agent.create({ name: 'Triage Agent', instructions: `Help the user with their questions. If the user asks about booking, hand off to the booking agent. If the user asks about refunds, hand off to the refund agent.`.trimStart(), handoffs: [bookingAgent, refundAgent],});
동적 instructions
섹션 제목: “동적 instructions”instructions
는 문자열 대신 함수 가 될 수 있습니다. 이 함수는 현재 RunContext
와 Agent 인스턴스를 받고 문자열 또는 Promise<string>
을 반환할 수 있습니다.
import { Agent, RunContext } from '@openai/agents';
interface UserContext { name: string;}
function buildInstructions(runContext: RunContext<UserContext>) { return `The user's name is ${runContext.context.name}. Be extra friendly!`;}
const agent = new Agent<UserContext>({ name: 'Personalized helper', instructions: buildInstructions,});
동기 및 async
함수가 모두 지원됩니다.
라이프사이클 훅
섹션 제목: “라이프사이클 훅”고급 사용 사례의 경우 이벤트를 수신하여 Agent 라이프사이클을 관찰할 수 있습니다. 사용 가능한 항목은 여기에 나열된 에이전트 훅 이벤트 이름을 참고하세요.
import { Agent } from '@openai/agents';
const agent = new Agent({ name: 'Verbose agent', instructions: 'Explain things thoroughly.',});
agent.on('agent_start', (ctx, agent) => { console.log(`[${agent.name}] started`);});agent.on('agent_end', (ctx, output) => { console.log(`[agent] produced:`, output);});
가드레일
섹션 제목: “가드레일”가드레일을 사용하면 사용자 입력과 에이전트 출력을 검증하거나 변환할 수 있습니다. inputGuardrails
및 outputGuardrails
배열을 통해 구성합니다. 자세한 내용은 가드레일을 참고하세요.
에이전트 복제/복사
섹션 제목: “에이전트 복제/복사”기존 에이전트의 약간 수정된 버전이 필요하신가요? 새로운 Agent
인스턴스를 반환하는 clone()
메서드를 사용하세요.
import { Agent } from '@openai/agents';
const pirateAgent = new Agent({ name: 'Pirate', instructions: 'Respond like a pirate – lots of “Arrr!”', model: 'gpt-5-mini',});
const robotAgent = pirateAgent.clone({ name: 'Robot', instructions: 'Respond like a robot – be precise and factual.',});
도구 사용 강제
섹션 제목: “도구 사용 강제”도구를 제공해도 LLM이 반드시 호출하는 것은 아닙니다. modelSettings.tool_choice
로 도구 사용을 강제 할 수 있습니다:
'auto'
(기본값) – LLM이 도구 사용 여부를 결정'required'
– LLM은 반드시 도구를 호출해야 함(어떤 도구를 사용할지는 선택 가능)'none'
– LLM은 도구를 호출하면 안 됨- 특정 도구 이름(예:
'calculator'
) – LLM은 해당 도구를 반드시 호출해야 함
import { Agent, tool } from '@openai/agents';import { z } from 'zod';
const calculatorTool = tool({ name: 'Calculator', description: 'Use this tool to answer questions about math problems.', parameters: z.object({ question: z.string() }), execute: async (input) => { throw new Error('TODO: implement this'); },});
const agent = new Agent({ name: 'Strict tool user', instructions: 'Always answer using the calculator tool.', tools: [calculatorTool], modelSettings: { toolChoice: 'auto' },});
무한 루프 방지
섹션 제목: “무한 루프 방지”도구 호출 후 SDK는 자동으로 tool_choice
를 'auto'
로 재설정합니다. 이는 모델이 도구를 반복적으로 호출하려는 무한 루프에 빠지는 것을 방지합니다. 이 동작은 resetToolChoice
플래그 또는 toolUseBehavior
구성으로 재정의할 수 있습니다:
'run_llm_again'
(기본값) – 도구 결과와 함께 LLM을 다시 실행'stop_on_first_tool'
– 첫 번째 도구 결과를 최종 답변으로 처리{ stopAtToolNames: ['my_tool'] }
– 나열된 도구 중 하나가 호출되면 중지(context, toolResults) => ...
– 실행 종료 여부를 반환하는 사용자 정의 함수
const agent = new Agent({ ..., toolUseBehavior: 'stop_on_first_tool',});