에이전트 만들기

에이전트 만들기

OpenAI Agents SDK에서 Agent는 모든 것의 기본 단위예요. 에이전트는 시스템 프롬프트 역할을 하는 instructions, 호출할 모델, 그리고 도구(tools)를 지닌 LLM이라고 보면 돼요. SDK의 구조는 OpenAI의 Responses API를 기본으로 하지만, 진짜 핵심은 "오케스트레이션"이에요. Agent와 Runner가 대화 턴, 도구 호출, 가드레일, 핸드오프, 세션을 알아서 관리해 주기 때문이에요.

가장 단순한 에이전트는 Agent에 이름과 지시만 넣으면 돼요. instructions는 문자열이 될 수도 있고, 컨텍스트를 받아 동적으로 만드는 함수가 될 수도 있어요. 실제 호출은 Runner.run()에 에이전트와 입력을 넘기는 걸로 시작해요.

from agents import Agent, Runner

agent = Agent(
    name="Customer support agent",
    instructions="You are a customer support agent. Help users with their questions.",
)

result = Runner.run_sync(agent, "My order hasn't arrived yet")
print(result.final_output)

출처: https://openai.github.io/openai-agents-python/agents/

기본 구성 요소

에이전트에 붙일 수 있는 대표 설정은 이렇게 정리할 수 있어요.

  • instructions: 시스템 프롬프트입니다. 에이전트가 누구인지, 어떻게 응답해야 하는지 결정해요.
  • model: 기본 모델을 쓰려면 생략해도 되고, 명시하고 싶으면 여기에 모델명을 넣으면 돼요.
  • tools: 에이전트가 작업을 끝내기 위해 호출할 수 있는 함수·API 목록이에요.
  • output_type: 출력을 일반 텍스트가 아니라 구조화된 값으로 강제하고 싶을 때 써요 (Agent.output_type).
  • handoffs: 다른 에이전트로 대화를 넘겨주는 핸드오프 목록이에요.
  • input_guardrails / output_guardrails: 입력·출력에 대한 검증 함수예요.

context는 의존성 주입 도구예요. Runner.run()에 넘긴 컨텍스트 객체는 에이전트·도구·핸드오프에 모두 전달되며, 실행에 필요한 상태나 객체를 담는 "잡동사니 주머니" 역할을 해요.

from dataclasses import dataclass
from agents import Agent, Runner

@dataclass
class UserContext:
    uid: str
    is_pro_user: bool

agent = Agent[UserContext](
    name="Assistant",
    instructions="Help the user.",
)

출력 타입

output_type을 지정하면 에이전트의 최종 출력이 해당 형태로 보장돼요. Pydantic 모델이나 TypedDict 형식의 스키마를 넘기면 SDK가 그 구조를 강제해요. 자세한 내용은 결과(Results) 가이드에서 다뤄요.

멀티 에이전트 패턴

여러 에이전트를 설계할 때 흔히 쓰는 두 가지 패턴이 있어요.

  1. Manager (tools as agents): 중앙 관리 에이전트가 전문화된 하위 에이전트를 도구로 호출하고 대화의 통제권을 계속 잡아요.
  2. Handoffs: 동료 에이전트가 전문화된 에이전트에게 대화를 넘겨주는 분산 방식이에요.
from agents import Agent

booking_agent = Agent(name="Booking agent")
refund_agent = Agent(name="Refund agent")

customer_facing_agent = Agent(
    name="Customer-facing agent",
    instructions="Handle booking and refund requests.",
    handoffs=[booking_agent, refund_agent],
)

더 알아보기