For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
기본 탐색 메뉴
Theme

에이전트 정의

더 큰 워크플로우로 확장하기 전에 에이전트 하나의 역할과 동작을 명확히 설정하세요.

에이전트는 SDK 기반 워크플로우의 기본 단위입니다. 에이전트에는 모델과 지침이 포함되며, 필요에 따라 도구, 가드레일, MCP 서버, 핸드오프, 구조화된 출력값 등 런타임에 사용할 기능을 추가할 수 있습니다.

에이전트에서 설정할 항목

특정 에이전트의 역할에 따라 달라지는 사항은 해당 에이전트에서 설정하세요.

속성 용도 관련 문서
name 트레이스와 도구·핸드오프 인터페이스에서 사람이 알아볼 수 있는 이름 지정 이 페이지
instructions 에이전트의 작업, 제약 조건, 응답 스타일 지정 이 페이지
prompt Responses API 기반 실행에서 저장된 프롬프트 설정 사용 모델 및 제공업체
model 및 모델 설정 모델 선택 및 동작 조정 모델 및 제공업체
tools 에이전트가 직접 호출할 수 있는 기능 지정 도구 사용
handoffDescription 다른 에이전트가 어떤 경우에 이 에이전트에 작업을 위임해야 하는지 안내 오케스트레이션 및 핸드오프
handoffs 다른 에이전트에 작업 위임 오케스트레이션 및 핸드오프
outputType 일반 텍스트 대신 구조화된 출력값 반환 이 페이지
가드레일 및 승인 검증, 차단, 검토 플로우 구성 가드레일 및 사람의 검토
MCP 서버 및 호스팅형 MCP 도구 MCP 기반 기능 연결 통합 및 관측 가능성

한 가지 작업을 맡는 에이전트로 시작하기

명확한 작업 하나를 수행하는 데 필요한 최소한의 구성으로 에이전트를 정의하세요. 역할을 분리해야 하거나 서로 다른 지침, 도구 인터페이스 또는 승인 정책이 필요할 때만 에이전트를 추가하세요.

에이전트 하나 정의하기
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-6-astra",
  tools: [getWeather],
});

지침, 핸드오프, 출력 설정하기

다음 세 가지 항목은 특히 주의해서 설정하세요.

  • 먼저 정적 instructions를 사용하세요. 현재 사용자, 테넌트 또는 런타임 컨텍스트에 따라 지침이 달라진다면 호출 지점에서 문자열을 조합하는 대신 콜백으로 지침을 동적으로 생성하세요.
  • handoffDescription에는 짧고 구체적인 설명을 작성하세요. 라우팅을 담당하는 에이전트가 어떤 경우에 이 전문 에이전트를 선택해야 하는지 알 수 있어야 합니다.
  • 후속 처리 코드에 자유 형식의 텍스트 대신 타입이 지정된 데이터가 필요하다면 outputType을 사용하세요.
구조화된 출력값 반환하기
import { Agent, run } from "@openai/agents";
import { z } from "zod";

const calendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const agent = new Agent({
  name: "Calendar extractor",
  instructions: "Extract calendar events from text.",
  outputType: calendarEvent,
});

const result = await run(agent, "Dinner with Priya and Sam on Friday.");

console.log(result.finalOutput);

시스템 프롬프트 전체를 코드에 넣는 대신 Responses API에 저장된 프롬프트 설정을 참조하려면 prompt를 사용하세요.

로컬 컨텍스트와 모델 컨텍스트 구분하기

SDK에서는 애플리케이션 상태와 종속성을 모델에 보내지 않고도 에이전트 실행 시 전달할 수 있습니다. 인증된 사용자 정보, 데이터베이스 클라이언트, 로거, 헬퍼 함수 등을 전달할 때 이 방식을 사용하세요.

도구에 로컬 컨텍스트 전달하기
import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const fetchUserAge = tool({
  name: "fetch_user_age",
  description: "Return the age of the current user.",
  parameters: z.object({}),
  // TypeScript users can type this as RunContext<{ name: string; uid: number }>.
  async execute(_args, runContext) {
    return `User ${runContext?.context.name} is 47 years old`;
  },
});

const agent = new Agent({
  name: "Assistant",
  tools: [fetchUserAge],
});

const result = await run(agent, "What is the age of the user?", {
  context: { name: "John", uid: 123 },
});

console.log(result.finalOutput);

두 컨텍스트는 누가 정보에 접근하는지에 따라 구분합니다.

  • 모델은 대화 기록을 볼 수 있습니다.
  • 코드는 실행 컨텍스트에 접근할 수 있습니다.

모델에 필요한 정보는 지침이나 입력에 포함하거나 검색 또는 도구를 통해 제공하세요. 런타임에서만 필요한 정보는 로컬 컨텍스트에 보관하세요.

에이전트를 여러 개로 나눌 시점

전문 에이전트 하나에 응답 전체를 맡기는 것이 적절하지 않거나 작업별로 필요한 기능이 크게 다르면 에이전트를 나누세요. 대표적인 경우는 다음과 같습니다.

  • 전문 에이전트에 다른 도구나 MCP 인터페이스가 필요합니다.
  • 전문 에이전트에 다른 승인 정책이나 가드레일이 필요합니다.
  • 워크플로우의 특정 분기에서 다른 모델이나 출력 스타일이 필요합니다.
  • 하나의 긴 프롬프트로 처리하는 대신 트레이스에서 라우팅 경로를 명확하게 확인하고 싶습니다.

다음 단계

전문 에이전트 하나의 역할과 동작을 명확히 정의했다면 다음으로 결정할 사항에 맞는 가이드를 살펴보세요.