에이전트

에이전트는 OpenAI Agents SDK의 핵심 구성 요소입니다. 에이전트는 다음과 같이 설정된 대규모 언어 모델(LLM)입니다.

지침 – 모델에 자신이 누구인지와 어떻게 응답해야 하는지 알려주는 시스템 프롬프트입니다.
모델 – 호출할 OpenAI 모델과 선택적 모델 조정 매개변수입니다.
도구 – 작업을 수행하기 위해 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`	아니요	SDK가 함수 도구 결과를 모델에 다시 전송할지, 함수 도구 결과를 실행의 최종 출력으로 사용할지 제어합니다. 도구 사용 강제를 참조하세요.
`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({...}))
Standard JSON Schema로 변환할 수 있는 지원되는 Standard Schema 값
모든 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을 사용합니다.

Zod와 지원되는 Standard Schema 값은 파싱된 출력을 로컬에서 검증하고 추론된 출력 유형을 유지합니다. 원문 JSON Schema는 모델 계약을 설명하지만 파싱된 결과는 unknown으로 유지됩니다. Standard Schema 예제와 지원되는 검증 범위는 스키마 검증을 참조하세요.

OpenAI 플랫폼 매핑

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

SDK 개념	OpenAI 가이드	필요한 경우
`outputType`	Structured Outputs	에이전트가 텍스트 대신 유형이 지정된 JSON 또는 스키마로 검증된 객체를 반환해야 하는 경우
`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와 에이전트 인스턴스를 받고 문자열 또는 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는 전체 실행에 걸쳐 동일한 이름의 이벤트를 하나의 스트림으로 발생시킵니다. 핸드오프와 도구 호출을 한곳에서 관찰하려는 다중 에이전트 워크플로에 유용합니다.

공유되는 이벤트 이름은 다음과 같습니다.

이벤트	에이전트 훅 인수	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.',
});

clone()은 tools, handoffs, mcpServers, inputGuardrails, outputGuardrails와 같은 목록 속성을 복사하지 않습니다. 복제 설정에서 이러한 속성 중 하나를 생략하면 원래 에이전트와 복제본이 같은 배열을 공유하므로 어느 에이전트에서든 배열을 변경하면 두 에이전트 모두에 영향을 줍니다. 복제본이 자체 배열을 사용하도록 하려면 tools: [...agent.tools, extraTool]과 같은 새 배열을 전달하세요. 이 새 배열의 항목은 여전히 동일한 도구 또는 핸드오프 객체입니다. 목록 속성에 undefined를 전달하면 해당 속성을 제공한 것으로 간주되며, 원래 배열을 상속하는 대신 빈 목록으로 시작합니다.

도구 사용 강제

도구를 제공한다고 해서 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()와 같은 지연된 Responses 도구, deferLoading: true가 설정된 함수 도구 또는 deferLoading: true가 설정된 호스티드 MCP 도구를 사용할 때는 modelSettings.toolChoice를 'auto'로 유지하세요. 모델이 이러한 정의를 로드할 시점을 결정해야 하므로 SDK는 지연된 도구 또는 내장 tool_search 도우미를 이름으로 강제하는 것을 허용하지 않습니다. 전체 도구 검색 설정은 도구를 참조하세요.

무한 루프 방지

도구 호출 후 SDK는 자동으로 toolChoice를 'auto'로 재설정합니다. 이렇게 하면 모델이 도구 호출을 반복적으로 시도하는 무한 루프에 빠지는 것을 방지할 수 있습니다. resetToolChoice 플래그를 사용하거나 toolUseBehavior를 설정하여 이 동작을 재정의할 수 있습니다.

'run_llm_again'(기본값) – 도구 결과와 함께 LLM을 다시 실행합니다.
'stop_on_first_tool' – 첫 번째 도구 결과를 최종 답변으로 처리합니다.
{ stopAtToolNames: ['my_tool'] } – 목록에 있는 도구 중 하나가 호출되면 중지합니다.
(context, toolResults) => ... – 실행을 종료할지 여부를 반환하는 사용자 지정 함수입니다.

import { Agent, tool } from '@openai/agents';
import { z } from 'zod';

const calculatorTool = tool({
  name: 'calculator',
  description: 'Add two numbers.',
  parameters: z.object({ left: z.number(), right: z.number() }),
  execute: async ({ left, right }) => left + right,
});

const agent = new Agent({
  name: 'Calculator agent',
  instructions: 'Use the calculator tool to answer arithmetic questions.',
  tools: [calculatorTool],
  toolUseBehavior: 'stop_on_first_tool',
});

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

모델 선택, 저장된 프롬프트 및 제공자 설정은 모델을 참조하세요.
함수 도구, 호스티드 툴, MCP 및 agent.asTool()은 도구를 참조하세요.
매니저, 핸드오프 및 코드 기반 오케스트레이션 중 선택하는 방법은 에이전트 오케스트레이션을 참조하세요.
전문 에이전트 위임 설정은 핸드오프를 참조하세요.
턴 실행, 스트리밍 및 대화 상태는 에이전트 실행을 참조하세요.
finalOutput, 실행 항목 및 재개 상태는 실행 결과를 참조하세요.
사이드바의 @openai/agents 아래에서 전체 TypeDoc 레퍼런스를 살펴보세요.