DSPy로 AI 에이전트 만들기

DSPy로 AI 에이전트 만들기 (Build AI Agents with DSPy)

이 튜토리얼에서는 DSPy로 AI 에이전트를 만드는 방법을 차근차근 배웁니다. AI 에이전트란 환경을 자율적으로 인식하고, 결정을 내리고, 특정 목표를 달성하기 위해 행동하는 시스템입니다. 단일 모델 프롬프트와 달리, 에이전트는 보통 추론·계획·행동의 루프를 따르며, 검색 엔진·API·메모리 같은 도구를 통합해 복잡한 작업을 완료합니다.

출처: 문서

본문

이 튜토리얼은 대중적인 AI 에이전트 아키텍처 중 하나인 ReAct에 집중합니다. ReAct는 Re asoning(추론)과 Act ing(행동)의 줄임말로, LM에 작업 설명과 도구 목록을 주고, 더 많은 관찰을 위해 도구를 호출할지 또는 최종 출력을 생성할지 LM이 결정하게 합니다.

데모로 다음을 할 수 있는 간단한 항공사 고객 서비스 에이전트를 만들어 볼게요:

사용자 대신 새 여행을 예약.
항공편 변경과 취소를 포함해 기존 여행을 수정.
처리할 수 없는 작업에 고객 지원 티켓을 발행.

dspy.ReAct 모듈로 만들겠습니다.

의존성 설치

시작 전에 필요한 패키지를 설치합니다:

!pip install -qU dspy pydantic

권장: MLflow Tracing을 설정하세요(설정은 튜토리얼 내 안내를 따르면 됩니다).

도구 정의

에이전트가 인간 항공사 서비스 직원처럼 행동하도록 도구 목록을 준비합니다:

fetch_flight_info: 특정 날짜의 항공편 정보를 가져옴.
pick_flight: 어떤 기준에 따라 최적의 항공편을 고름.
book_flight: 사용자 대신 항공편을 예약.
fetch_itinerary: 예약된 일정(itinerary)의 정보를 가져옴.
cancel_itinerary: 예약된 일정을 취소.
get_user_info: 사용자 정보를 가져옴.
file_ticket: 인간 지원을 받도록 백로그 티켓을 발행.

데이터 구조 정의

도구를 정의하기 전에 데이터 구조를 정의합니다. 실제 프로덕션에서는 이것이 데이터베이스 스키마가 될 것입니다. 데모에서는 단순함을 위해 데이터 구조를 pydantic 모델로 정의합니다.

from pydantic import BaseModel

class Date(BaseModel):
    # Somehow LLM is bad at specifying `datetime.datetime`, so
    # we define a custom class to represent the date.
    year: int
    month: int
    day: int
    hour: int

class UserProfile(BaseModel):
    user_id: str
    name: str
    email: str

class Flight(BaseModel):
    flight_id: str
    date_time: Date
    origin: str
    destination: str
    duration: float
    price: float

class Itinerary(BaseModel):
    confirmation_number: str
    user_profile: UserProfile
    flight: Flight

class Ticket(BaseModel):
    user_request: str
    user_profile: UserProfile

더미 데이터 생성

항공사 에이전트가 작업할 수 있도록 더미 데이터를 만듭니다. 항공편 몇 개와 사용자 몇 명을 만들고, 일정과 고객 지원 티켓용 빈 사전을 초기화합니다.

도구 정의

각 도구를 평범한 Python 함수로 구현합니다. DSPy는 이름, 매개변수, docstring을 읽어 모델에게 지시문으로 제시합니다.

ReAct 에이전트 생성

이제 dspy.ReAct 로 ReAct 에이전트를 만들 수 있습니다. dspy.ReAct 에 에이전트의 작업·입력·출력을 정의할 시그니처를 제공하고, 접근할 수 있는 도구를 알려 줍니다.

class DSPyAirlineCustomerService(dspy.Signature):
    """You are an airline customer service agent that helps user book and manage flights.
    ...
    """

agent = dspy.ReAct(
    DSPyAirlineCustomerService,
    tools=[...],  # 정의한 도구들
    ...
)

에이전트 사용하기

에이전트와 상호작용하려면 user_request 를 통해 요청을 주면, 에이전트가 작업을 시작합니다.

result = agent(user_request="please help me book a flight from SFO to JFK on 09/01/2025, my name is Adam")

결과 값에는 reasoning(추론 근거)과 process_result(사용자가 알아야 할 요약 메시지, 예: 새 항공편을 예약했다면 confirmation_number)가 포함됩니다.

결과 해석하기

에이전트는 "SFO에서 JFK로, 09/01/2025" 항공편을 검색하고, 두 항공편(1 AM에 $200짜리 DA123, 7 AM에 $500짜리 DA125)을 찾은 뒤 더 싼 DA123을 고르고, 사용자 프로필을 가져와 예약을 진행하고, 예약 번호를 받았습니다. 다른 예시에서는 사용자가 DA125 로 변경을 요청했는데, 일정을 조회할 수 없어 고객 지원 티켓(lf3n2t)을 발행해 변경을 요청하는 흐름도 보여줍니다.

결론

튜토리얼을 마쳤습니다! DSPy로 고객 서비스 에이전트를 구축하는 법을 보았어요. 핵심은:

pydantic 모델로 도구 입력·출력의 구조를 명확히 정의하고,
평범한 Python 함수로 도구를 구현하고,
dspy.ReAct 로 에이전트 루프를 구성하며,
에이전트가 처리 못 하는 일은 티켓 발행으로 안전하게 위임한다는 것입니다.

DSPy로 AI 에이전트 만들기