Pydantic AI 시작하기 — 에러 없는 AI 에이전트 쉽게 만드는 법

AI 에이전트를 직접 만들어보려고 코드를 짜다가, 예상치 못한 데이터 형식 에러 때문에 작동이 멈춰서 당황했던 경험이 있으신가요? LLM이 준 답변이 내가 원한 데이터 규격과 맞지 않아 생기는 에러는 에이전트 개발에서 가장 흔하게 만나는 골칫거리입니다.

복잡한 프레임워크를 새로 공부할 필요 없이 파이썬 개발자에게 가장 친숙한 Pydantic 팀이 만든 'Pydantic AI'로 이 문제를 어떻게 깔끔하게 해결할 수 있는지 알아봅시다.

Pydantic AI가 다른 에이전트 도구와 다른 점

AI 에이전트를 직접 만들려고 기존 프레임워크들을 살펴보면 생각보다 공부할 게 너무 많아 숨이 턱 막히곤 합니다. 생소한 개념과 복잡하게 얽힌 구조 때문에 간단한 기능을 하나 구현하는 데도 꽤 많은 시간을 허비해야 하죠. 하지만 Pydantic AI는 파이썬 개발자에게 가장 익숙하고 직관적인 방식을 제안합니다.

Pydantic AI의 가장 큰 매력은 바로 '타입 안전성'을 제공한다는 점입니다. 이해를 돕기 위해 어릴 적 가지고 놀던 도형 맞추기 장난감을 떠올려 보세요. 세모 모양 구멍에는 세모 블록만 들어가고, 네모 구멍에는 네모 블록만 통과할 수 있는 장난감 틀처럼 작동하는 규칙입니다.

원래 거대 언어 모델은 자유롭게 아무 말이나 뱉어내는 성향이 있어서, 우리가 원하는 정확한 형식의 데이터를 받아내기가 쉽지 않습니다. Pydantic AI는 이 도형 맞추기 장난감처럼 인공지능이 주고받는 모든 데이터의 입구와 출구를 엄격하게 검증합니다. 덕분에 엉뚱한 형식의 데이터가 흘러 들어가 프로그램이 멈추는 에러를 원천 차단해 줍니다.

결국 복잡한 프레임워크의 규칙을 새로 배울 필요 없이, 평소 파이썬 코드를 짜듯 편안하게 개발할 수 있습니다. 가볍고 익숙한 문법을 유지하면서도 대규모 서비스에 바로 투입할 수 있을 만큼 단단하고 안전한 에이전트를 만들 수 있는 이유입니다.

두 가지 도구 연결법 — 일반 함수와 컨텍스트 맞춤형 함수

에이전트가 똑똑하게 일하려면 외부 데이터를 가져오거나 특정 작업을 수행할 수 있는 '도구'가 필요합니다. Pydantic AI에서는 복잡한 과정 없이 파이썬 데코레이터 하나만 얹어서 에이전트에게 강력한 도구를 쥐어줄 수 있습니다. 이때 상황에 맞춰 @agent.tool_plain과 @agent.tool 두 가지 데코레이터를 골라 쓰면 됩니다.

우선 @agent.tool_plain은 외부 상태나 추가 정보가 전혀 필요 없는 단순한 기능을 도구로 만들 때 씁니다. 예를 들어 입력받은 값을 계산하거나 단순히 날씨 API를 호출하는 작업처럼 독립적으로 실행할 수 있는 함수에 제격입니다.

반면 데이터베이스 연결 상태나 현재 로그인한 사용자의 ID처럼 에이전트가 실행되는 시점의 유동적인 정보가 필요할 때는 @agent.tool을 사용합니다. 이때 함께 제공되는 RunContext가 실행 도중 필요한 의존성을 에이전트 내부에 안전하게 주입해 주는 비서 역할을 합니다.

두 도구의 차이점과 사용법은 아래 파이썬 코드를 보면 한눈에 이해하실 수 있습니다.

from pydantic_ai import Agent, RunContext

# 에이전트를 만들고 주입할 의존성 타입을 str로 지정합니다.
agent = Agent('openai:gpt-4o', deps_type=str)

# 1. 단순 계산이나 고정된 데이터 조회용 (컨텍스트 불필요)
@agent.tool_plain
def calculate_square(x: int) -> int:
    return x * x

# 2. 실행 시점에 주입된 데이터나 DB 연결 등이 필요한 경우
@agent.tool
def get_user_profile(ctx: RunContext[str]) -> str:
    # ctx.deps에 실행할 때 넘겨준 사용자 ID가 안전하게 전달됩니다.
    return f"사용자 ID {ctx.deps}의 프로필 정보입니다."

이처럼 데이터베이스 연결이나 사용자 세션 정보처럼 매번 바뀌는 동적 데이터도 RunContext 덕분에 오류 없이 안전하고 깔끔하게 다룰 수 있습니다. 개발자는 복잡한 데이터 전달 로직에 머리를 싸매지 않고 오직 도구의 핵심 기능 개발에만 집중할 수 있게 됩니다.

로그파이어 연동으로 에이전트 속 시원하게 들여다보기

에이전트를 실행했을 때 '내부에서 대체 무슨 일이 일어나고 있는지' 모르는 답답함, 다들 한 번쯤 느껴보셨을 겁니다. LLM이 어떤 답변을 보내왔는지, 토큰은 얼마나 썼는지, 우리가 등록해 둔 도구는 제대로 호출했는지 눈으로 직접 확인하기란 쉽지 않죠.

이러한 답답함을 단 몇 줄의 코드로 날려버릴 수 있는 모니터링 도구가 바로 로그파이어(Logfire)입니다. Pydantic AI는 같은 팀에서 만든 로그파이어와 완벽하게 연결되도록 설계되어 있어, 복잡한 연동 과정 없이도 시각적인 타임라인을 통해 작동 과정을 투명하게 추적할 수 있습니다.

다음과 같이 코드 첫머리에 간단히 추가해주기만 하면 설정이 끝납니다.

import logfire

# 로그파이어 설정 및 Pydantic AI 추적 활성화
logfire.configure()
logfire.instrument_pydantic_ai()

이제 에이전트를 실행하면 대시보드에서 각 단계의 실행 시간, 호출한 LLM 종류, 실제 토큰 소모량까지 한눈에 볼 수 있습니다. 어디서 에러가 났고 어디서 병목이 생겼는지 바로 짚어낼 수 있으니 에이전트 개발이 훨씬 수월해집니다.

이제 나만의 안전한 에이전트를 빌드해 보세요

복잡한 AI 프레임워크의 개념들에 압도당할 필요는 전혀 없습니다. Pydantic AI와 로그파이어를 사용하면 가벼운 라이브러리 설치만으로 에러 없는 나만의 에이전트를 바로 시작할 수 있으니까요.

처음에는 오늘 배운 내용을 활용해서 간단한 아침 날씨 알리미나 매일 뉴스 피드를 요약해 주는 개인 업무 자동화 에이전트부터 가볍게 만들어 보세요. 직접 코드를 짜고 로그로 작동 과정을 실시간으로 확인하다 보면, 에이전트 개발이 훨씬 더 쉽고 흥미롭게 느껴질 것입니다.

생산성을 한 단계 높여줄 나만의 똑똑하고 안전한 AI 비서 만들기, 지금 바로 가볍게 도전해 보는 건 어떨까요?