에이전트

에이전트는 OpenAI Agents SDK의 주요 구성 요소입니다. 에이전트는 다음과 같이 설정된 대규모 언어 모델(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.4', // optional – falls back to the default model
});

단일 Agent를 정의하거나 사용자 지정하려면 이 페이지를 사용하세요. 여러 에이전트의 협업 방식을 결정하려면 에이전트 오케스트레이션을 읽어보세요.

다음 가이드 선택

이 페이지를 에이전트 정의의 중심 가이드로 활용하세요. 다음으로 결정해야 할 사항에 맞는 관련 가이드로 이동할 수 있습니다.

원하는 작업	다음 가이드
모델 선택 또는 저장된 프롬프트 설정	모델
에이전트에 기능 추가	도구
에이전트에 격리된 파일 시스템 작업 공간 제공	개념
관리자와 핸드오프 중에서 선택	에이전트 오케스트레이션
핸드오프 동작 설정	핸드오프
턴 실행, 이벤트 스트리밍 또는 상태 관리	에이전트 실행
최종 출력이나 실행 항목 검사 또는 실행 재개	실행 결과

이 페이지의 나머지 부분에서는 에이전트의 모든 기능을 더 자세히 설명합니다.

에이전트 기본 사항

기본 설정

Agent 생성자는 하나의 설정 객체를 받습니다. 가장 자주 사용되는 속성은 다음과 같습니다.

속성	필수 여부	설명
`name`	예	사람이 읽을 수 있는 짧은 식별자
`instructions`	예	시스템 프롬프트(문자열 또는 함수 — 동적 instructions 참조)
`prompt`	아니요	OpenAI Responses API 프롬프트 설정입니다. 정적 프롬프트 객체 또는 함수를 받습니다. 프롬프트를 참조하세요.
`handoffDescription`	아니요	이 에이전트가 핸드오프 도구로 제공될 때 사용하는 간단한 설명
`handoffs`	아니요	대화를 전문 에이전트에게 위임합니다. 구성 패턴과 핸드오프를 참조하세요.
`model`	아니요	모델 이름 또는 사용자 지정 `Model` 구현
`modelSettings`	아니요	조정 매개변수(temperature, top_p 등)입니다. 모델을 참조하세요. 필요한 속성이 최상위 수준에 없다면 `providerData` 아래에 포함할 수 있습니다.
`tools`	아니요	모델이 호출할 수 있는 `Tool` 인스턴스의 배열입니다. 도구를 참조하세요.
`mcpServers`	아니요	에이전트에서 사용하는 MCP 기반 도구입니다. 모델 컨텍스트 프로토콜 (MCP)를 참조하세요.
`mcpConfig`	아니요	엄격한 스키마, 오류 처리, 서버 접두사가 붙은 도구 이름 등 로컬 MCP 도구의 옵션입니다. 에이전트 수준 MCP 설정을 참조하세요.
`inputGuardrails`	아니요	이 에이전트 체인의 첫 번째 사용자 입력에 적용되는 가드레일입니다. 가드레일을 참조하세요.
`outputGuardrails`	아니요	이 에이전트의 최종 출력에 적용되는 가드레일입니다. 가드레일을 참조하세요.
`outputType`	아니요	일반 텍스트 대신 구조화된 출력을 반환합니다. 출력 타입과 실행 결과를 참조하세요.
`toolUseBehavior`	아니요	함수 도구 결과를 모델에 다시 전달할지 또는 실행을 종료할지 제어합니다. 도구 사용 강제를 참조하세요.
`resetToolChoice`	아니요	도구 사용 루프를 방지하기 위해 도구 호출 후 `toolChoice`를 기본값으로 재설정합니다(기본값: `true`). 도구 사용 강제를 참조하세요.
`handoffOutputTypeWarningEnabled`	아니요	핸드오프 출력 타입이 서로 다를 때 경고를 표시합니다(기본값: `true`). 실행 결과를 참조하세요.

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()에 전달하는 의존성 주입 객체입니다. 모든 도구, 가드레일, 핸드오프 등에 전달되며 상태을 저장하거나 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등)를 제공할 때 유용합니다.

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.',
});

// Later
import { run } from '@openai/agents';

const result = await run(agent, 'Find me a new pair of running shoes', {
  context: { uid: 'abc', isProUser: true, fetchPurchases: async () => [] },
});

출력 타입

기본적으로 에이전트는 일반 텍스트(string)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 outputType 속성을 지정할 수 있습니다. SDK는 다음을 지원합니다.

Zod 스키마(z.object({...}))
모든 JSON 스키마 호환 객체

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를 사용합니다.

OpenAI 플랫폼 매핑

일부 에이전트 개념은 OpenAI 플랫폼 개념에 직접 매핑되지만, 다른 개념은 에이전트를 정의할 때가 아니라 실행할 때 설정합니다.

SDK 개념	OpenAI 가이드	적용 시점
`outputType`	Structured Outputs	에이전트가 텍스트 대신 타입이 지정된 JSON 또는 Zod로 검증된 객체를 반환해야 할 때
`tools` / 호스티드 툴	도구 가이드	모델이 검색, 조회, 코드 실행 또는 사용자의 함수나 도구 호출을 수행해야 할 때
`conversationId` / `previousResponseId`	대화 상태	OpenAI가 턴 간 대화 상태를 유지하거나 연결하도록 하려는 경우

conversationId와 previousResponseId는 런타임 제어 항목이며 Agent 생성자의 필드가 아닙니다. 이러한 SDK 진입점이 필요하면 에이전트 실행을 참조하세요.

구성 패턴

에이전트가 더 큰 워크플로에 참여할 때 가장 자주 사용되는 SDK 진입점은 다음 두 가지입니다.

관리자(agents as tools) – 중앙 에이전트가 대화를 담당하고 도구로 노출된 전문 에이전트를 호출합니다.
핸드오프 – 초기 에이전트가 사용자의 요청을 식별하면 전체 대화를 전문 에이전트에게 위임합니다.

두 접근 방식은 상호 보완적입니다. 관리자를 사용하면 한곳에서 가드레일이나 속도 제한을 적용할 수 있으며, 핸드오프를 사용하면 각 에이전트가 대화의 제어권을 유지하지 않고 단일 작업에 집중할 수 있습니다. 설계상의 장단점과 각 패턴의 선택 기준은 에이전트 오케스트레이션을 참조하세요.

관리자(agents as tools)

이 패턴에서 관리자는 제어권을 넘기지 않습니다. 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 handoffs
const 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],
});

핸드오프 대상이 서로 다른 출력 타입을 반환할 수 있다면 new Agent(...)보다 Agent.create(...)를 사용하는 것이 좋습니다. 그러면 TypeScript가 핸드오프 그래프 전체에서 가능한 finalOutput 형식의 유니온을 추론할 수 있으며, handoffOutputTypeWarningEnabled로 제어되는 런타임 경고를 방지할 수 있습니다. 전체 코드 예제는 실행 결과를 참조하세요.

고급 설정 및 런타임 제어

동적 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 함수를 모두 지원합니다.

동적 프롬프트

prompt는 instructions와 동일한 콜백 형식을 지원하지만 문자열 대신 프롬프트 설정 객체를 반환합니다. 현재 실행 컨텍스트에 따라 프롬프트 ID, 버전 또는 변수가 달라지는 경우 유용합니다.

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

interface PromptContext {
  customerTier: 'free' | 'pro';
}

function buildPrompt(runContext: RunContext<PromptContext>) {
  return {
    promptId: 'pmpt_support_agent',
    version: '7',
    variables: {
      customer_tier: runContext.context.customerTier,
    },
  };
}

const agent = new Agent<PromptContext>({
  name: 'Prompt-backed helper',
  prompt: buildPrompt,
});

OpenAI Responses API를 사용할 때만 지원됩니다. 동기 함수와 async 함수를 모두 지원합니다.

수명 주기 훅

고급 사용 사례에서는 이벤트를 수신하여 에이전트 수명 주기를 관찰할 수 있습니다.

Agent 인스턴스는 해당 에이전트 인스턴스에 대한 수명 주기 이벤트를 발생시키며, Runner는 전체 실행에 걸쳐 동일한 이름의 이벤트를 단일 스트림으로 발생시킵니다. 이는 핸드오프와 도구 호출을 한곳에서 관찰하려는 멀티 에이전트 워크플로에 유용합니다.

공통 이벤트 이름은 다음과 같습니다.

이벤트	Agent 훅 인수	Runner 훅 인수
`agent_start`	`(context, agent, turnInput?)`	`(context, agent, turnInput?)`
`agent_end`	`(context, output)`	`(context, agent, output)`
`agent_handoff`	`(context, nextAgent)`	`(context, fromAgent, toAgent)`
`agent_tool_start`	`(context, tool, { toolCall })`	`(context, agent, tool, { toolCall })`
`agent_tool_end`	`(context, tool, result, { toolCall })`	`(context, agent, tool, result, { toolCall })`

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.4',
});

const robotAgent = pirateAgent.clone({
  name: 'Robot',
  instructions: 'Respond like a robot – be precise and factual.',
});

도구 사용 강제

도구를 제공하더라도 LLM이 반드시 호출하는 것은 아닙니다. modelSettings.toolChoice를 사용하여 도구 사용을 강제할 수 있습니다.

'auto'(기본값) – LLM이 도구 사용 여부를 결정합니다.
'required' – LLM이 도구를 반드시 호출해야 합니다(호출할 도구는 선택할 수 있음).
'none' – LLM이 도구를 호출해서는 안 됩니다.
'calculator'와 같은 특정 도구 이름 – LLM이 해당 도구를 반드시 호출해야 합니다.

OpenAI Responses에서 사용 가능한 도구가 computerTool()인 경우 toolChoice: 'computer'에는 특별한 의미가 있습니다. 'computer'를 일반 함수 이름으로 처리하는 대신 GA 내장 컴퓨터 도구를 강제로 사용합니다. SDK는 이전 연동을 위한 프리뷰 호환 컴퓨터 선택자도 지원하지만, 새 코드에서는 'computer'를 사용하는 것이 좋습니다. 사용 가능한 컴퓨터 도구가 없으면 이 문자열은 다른 함수 도구 이름과 동일하게 동작합니다.

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: 'required' },
});

toolNamespace(), deferLoading: true가 지정된 함수 도구 또는 deferLoading: true가 지정된 호스티드 MCP 도구처럼 지연된 Responses 도구를 사용할 때는 modelSettings.toolChoice를 'auto'로 유지하세요. 모델이 해당 정의를 언제 로드할지 결정해야 하므로 SDK는 지연된 도구 또는 내장 tool_search 도우미를 이름으로 강제하는 것을 허용하지 않습니다. 전체 도구 검색 설정은 도구를 참조하세요.

무한 루프 방지

도구 호출 후 SDK는 toolChoice를 자동으로 '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',
});

참고: toolUseBehavior는 함수 도구에만 적용됩니다. 호스티드 툴은 항상 처리를 위해 모델로 결과를 반환합니다.