에이전트

에이전트는 OpenAI Agents SDK의 핵심 구성 요소입니다. Agent는 다음과 같이 구성된 Large Language Model (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 기능을 더 자세히 설명합니다.

에이전트 기초

기본 설정

Agent 생성자는 단일 설정 객체를 받습니다. 가장 자주 사용하는 속성은 아래와 같습니다.

속성	필수	설명
`name`	예	사람이 읽기 쉬운 짧은 식별자
`instructions`	예	시스템 프롬프트(문자열 또는 함수 - 동적 instructions 참고)
`prompt`	아니요	OpenAI Responses API 프롬프트 설정입니다. 정적 프롬프트 객체 또는 함수를 받을 수 있습니다. Prompt를 참고하세요
`handoffDescription`	아니요	이 에이전트가 핸드오프 도구로 제공될 때 사용되는 짧은 설명
`handoffs`	아니요	대화를 전문 에이전트에게 위임합니다. 구성 패턴 및 핸드오프 가이드를 참고하세요
`model`	아니요	모델 이름 또는 사용자 지정 `Model` 구현
`modelSettings`	아니요	튜닝 매개변수(temperature, top_p 등)입니다. 모델을 참고하세요. 필요한 속성이 최상위에 없다면 `providerData` 아래에 포함할 수 있습니다
`tools`	아니요	모델이 호출할 수 있는 `Tool` 인스턴스 배열입니다. 도구를 참고하세요
`mcpServers`	아니요	에이전트를 위한 MCP 기반 도구입니다. 모델 컨텍스트 프로토콜 (MCP) 가이드를 참고하세요
`mcpConfig`	아니요	strict 스키마, 오류 처리, 서버 접두사 도구 이름 등 로컬 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 () => [] },
});

출력 타입

기본적으로 Agent는 일반 텍스트(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` / hosted tools	Tools guide	모델이 검색, 조회, 코드 실행 또는 사용자 함수/도구 호출을 해야 할 때
`conversationId` / `previousResponseId`	Conversation state	턴 간 대화 상태를 OpenAI에 유지시키거나 연결하고 싶을 때

conversationId와 previousResponseId는 Agent 생성자 필드가 아니라 런타임 제어 항목입니다. 이런 SDK 진입점이 필요하다면 에이전트 실행을 사용하세요.

구성 패턴

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

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

이 접근 방식들은 상호 보완적입니다. 관리자는 가드레일이나 속도 제한을 강제할 단일 지점을 제공하고, 핸드오프는 각 에이전트가 대화의 제어권을 유지하지 않은 채 하나의 작업에만 집중할 수 있게 해줍니다. 설계상 트레이드오프와 각 패턴을 언제 선택해야 하는지는 에이전트 오케스트레이션을 참고하세요.

관리자(도구로서의 에이전트)

이 패턴에서는 관리자가 제어권을 넘기지 않습니다. 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 생명주기를 관찰할 수 있습니다.

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 배열로 설정합니다. 자세한 내용은 가드레일 가이드를 참고하세요.

에이전트 복제 / 복사

기존 에이전트를 약간 수정한 버전이 필요하신가요? clone() 메서드를 사용하면 완전히 새로운 Agent 인스턴스를 반환합니다.

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는 이전 통합을 위해 preview 호환 컴퓨터 선택자도 허용하지만, 새 코드에서는 '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()와 같은 지연된 Responses 도구, deferLoading: true가 설정된 함수 도구, 또는 deferLoading: true가 설정된 호스티드 MCP 도구를 사용할 때는 modelSettings.toolChoice를 'auto'로 유지하세요. SDK는 지연된 도구나 내장 tool_search 헬퍼를 이름으로 강제하는 것을 거부합니다. 모델이 해당 정의를 언제 로드할지 결정해야 하기 때문입니다. 전체 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는 함수 도구에만 적용됩니다. 호스티드 툴은 항상 처리를 위해 모델로 다시 반환됩니다.