smolagents vs Pydantic AI — 내게 맞는 파이썬 에이전트 프레임워크 선택 기준

Haram

@haram

smolagents vs Pydantic AI — 내게 맞는 파이썬 에이전트 프레임워크 선택 기준

smolagents vs Pydantic AI — 내게 맞는 파이썬 에이전트 프레임워크 선택 기준

요즘 나만의 AI 에이전트를 직접 만들어보고 싶어 하는 분들이 정말 많아졌습니다. 하지만 무겁고 복잡한 기존 프레임워크를 마주하는 순간, 높은 진입장벽에 막막함을 느끼기 일쑤인데요. 이런 고민을 시원하게 해결해 주기 위해 가벼우면서도 실용적인 두 가지 대세 도구, 허깅페이스의 smolagents와 Pydantic AI의 특징을 알기 쉽게 비교해 드리겠습니다.

LLM이 코드를 직접 실행한다: smolagents의 혁신

에이전트를 만들 때 가장 귀찮은 일은 무엇일까요? 바로 LLM에게 도구를 쥐여주고 사용법을 알려주는 과정입니다. 기존 방식은 AI가 특정 JSON 규격에 맞춰 답을 주면, 개발자가 그걸 하나하나 파싱해서 실행하는 복잡한 과정을 거쳐야 했습니다.

허깅페이스가 내놓은 smolagents는 이 번거로운 구조를 완전히 뒤집었습니다. LLM이 직접 파이썬 코드를 작성하고 이를 곧바로 실행하는 코드 실행형 에이전트 방식을 사용하거든요.

이 방식의 매력은 아주 명확합니다.

  • 복잡한 규격 생략: JSON 스키마를 억지로 설계하고 맞출 필요가 없습니다.
  • 강력한 프로그래밍 제어: 반복문이나 조건문 같은 흐름 제어를 LLM이 파이썬 코드로 직접 짜서 실행합니다.
  • 압도적인 가독성: 복잡한 체인이나 파이프라인 설계 없이 단 몇 줄이면 작동 가능한 에이전트가 완성됩니다.

최근 업데이트된 smolagents는 executor_type이라는 통합 파라미터를 사용해 에이전트가 코드를 실행할 환경을 아주 간단하게 지정할 수 있도록 바꿨습니다. 프로토타입을 빠르게 테스트해보고 싶다면 아래 코드처럼 단 한 줄만 적어주면 됩니다.

python
from smolagents import CodeAgent, DuckDuckGoSearchTool, HfApiClient

agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=HfApiClient(),
    executor_type="local"  # local 외에도 e2b, docker 등을 바로 지정할 수 있습니다
)

agent.run("2026년 가장 인기 있는 파이썬 라이브러리를 검색해줘.")

작동 방식이 아주 직관적이죠? 에이전트에게 원하는 미션과 활용할 도구만 쥐여주면, LLM이 스스로 파이썬 코드를 작성하고 실행하여 결과물만 깔끔하게 돌려줍니다.

타입 안정성과 데이터 제어: Pydantic AI가 빛나는 순간

앞서 소개한 smolagents가 LLM에게 파이썬 코딩을 직접 맡겨 자유도를 극대화하는 방식이라면, Pydantic AI는 반대로 LLM을 완벽하게 통제하고 싶은 개발자를 위한 든든한 도구입니다. 데이터의 형태를 엄격하게 제한하고 검증하여, 에이전트가 항상 약속된 규격의 안전한 결과물만 내놓도록 돕는 것이죠.

실제 서비스 운영 환경에서 LLM의 무한한 창의성은 때로 시스템을 멈추게 만드는 원인이 됩니다. AI가 뜬금없이 필수 항목을 빼놓고 결과를 보내거나, 숫자 필드에 텍스트를 채워 넣어 백엔드 서버에서 오류를 일으키는 상황이 대표적입니다. Pydantic AI는 파이썬 백엔드 개발자들에게 가장 익숙한 데이터 검증 기술을 사용해 이러한 오류를 원천 차단합니다.

Pydantic AI가 프로덕션 환경에서 유독 빛나는 이유는 다음과 같습니다.

  • 예측 가능한 출력: LLM이 항상 지정한 데이터 구조에 맞춰 정확한 타입을 반환하도록 강제합니다.
  • 스마트한 자체 교정: 유효성 검사에 실패하면 에이전트가 에러 정보를 바탕으로 LLM에게 다시 질문해 스스로 실수를 바로잡습니다.
  • 친숙한 개발 경험: 이미 수많은 파이썬 프로젝트에서 검증된 라이브러리 문법을 그대로 사용하여 기존 시스템과 쉽게 통합됩니다.

가장 강력한 매력은 데이터가 잘못되었을 때 개발자가 일일이 예외 처리를 작성할 필요가 없다는 점입니다. 에이전트가 내부 루프 안에서 타입 에러를 스스로 인식하고 수정하는 과정을 거치기 때문입니다. 실제로 어떻게 구현하는지 아주 간단한 설정 코드로 살펴보겠습니다.

python
from pydantic import BaseModel, Field
from pydantic_ai import Agent

# 1. 원하는 출력 데이터 구조를 정의합니다
class UserProfile(BaseModel):
    name: str
    age: int = Field(description="사용자의 나이")
    interests: list[str] = Field(description="관심사 목록")

# 2. 에이전트 생성 시 output_type에 모델을 넘겨줍니다
agent = Agent(
    'openai:gpt-4o-mini',
    output_type=UserProfile,
    system_prompt="사용자 정보를 정확하게 추출해 주세요."
)

# 3. 에이전트를 실행하면 검증된 객체가 바로 반환됩니다
result = agent.run_sync("25살이고 축구와 요리를 즐기는 김철수 씨 프로필 정리해줘.")
print(result.output)
# 결과: UserProfile(name='김철수', age=25, interests=['축구', '요리'])

코드가 정말 직관적이지 않나요? FastAPI 같은 최신 웹 프레임워크를 다루어 본 개발자라면 별도의 학습 없이도 즉시 고도화된 타입 안전 에이전트를 빌드할 수 있습니다.

보안 위협 해결: 안전한 실행을 위한 샌드박스 구성법

LLM이 내 컴퓨터에서 직접 파이썬 코드를 짠 다음 바로 실행해 준다니, 생각만 해도 짜릿하고 편리합니다. 하지만 여기서 등골이 서늘해지는 질문을 던져봐야 합니다. "만약 AI가 내 컴퓨터에 있는 중요한 파일을 전부 지워버리는 코드를 실행하면 어쩌지?"

실제로 로컬 환경에서 LLM이 작성한 코드를 그대로 실행하는 것은 매우 위험합니다. 악의적인 프롬프트 주입 공격을 받으면 로컬의 기본 보안 검사를 우회해 컴퓨터 내부의 파일을 멋대로 읽고 쓰거나 원격 제어 권한을 탈취당할 수 있기 때문입니다. 실제로 발견된 보안 취약점인 CVE-2025-9959가 이를 잘 보여주는 사례입니다.

다행히 smolagents는 이 문제를 아주 깔끔하고 안전하게 해결할 수 있는 장치를 마련해 두었습니다. 바로 executor_type이라는 옵션을 통해 코드를 완전히 격리된 독립 가상 공간, 즉 샌드박스에서만 실행하도록 제어하는 방법입니다.

다음과 같이 단 한 줄의 설정만으로 코드를 클라우드 가상환경(E2B)이나 도커 컨테이너 내부에서만 안전하게 실행할 수 있습니다.

python
from smolagents import CodeAgent, HfApiModel

# executor_type 하나로 안전한 실행 환경 구축하기
agent = CodeAgent(
    tools=[],
    model=HfApiModel(),
    executor_type="e2b"  # 'local', 'docker', 'modal' 등으로 쉽게 변경할 수 있습니다.
)

가장 대표적인 두 가지 안전장치는 다음과 같습니다.

  • E2B 클라우드 가상머신: executor_type="e2b" 설정을 사용하면, LLM이 작성한 코드가 내 컴퓨터가 아닌 E2B 클라우드의 격리된 환경에서 실행됩니다. 0.03초 만에 켜지는 깨끗한 일회용 컴퓨터를 빌려 쓰는 것과 같아 해킹 위협으로부터 완전히 안전합니다.
  • 로컬 도커 컨테이너: 클라우드 대신 내 컴퓨터 안에서 격리하고 싶다면 도커를 쓰면 됩니다. executor_type="docker"를 지정하면 내 컴퓨터 내부에 튼튼한 방화벽을 친 컨테이너 공간을 만들고, 그 안에서만 안전하게 파이썬 코드가 실행됩니다.

AI 에이전트의 막강한 능력을 100% 안전하게 누리기 위해서는 이러한 격리된 샌드박스 환경 설정이 선택이 아닌 필수라는 점을 꼭 기억해 주세요!

나에게 꼭 맞는 파이썬 에이전트 선택 기준

두 도구의 매력이 워낙 확실하다 보니, "그래서 내 프로젝트에는 뭘 써야 하지?" 하고 고민이 되실 겁니다. 여러분의 시간과 노력을 아껴드리기 위해 아주 직관적인 선택 기준을 정리해 드립니다.

이런 분들은 smolagents를 선택하세요

  • 빠른 프로토타이핑: 아이디어를 빠르게 검증하고 가벼운 자동화 도구를 뚝딱 만들고 싶을 때 제격입니다.
  • 유연한 문제 해결: AI가 직접 파이썬 코드를 작성하고 실행하면서 복잡한 계산이나 도구 제어를 자유롭게 하길 원할 때 강력한 힘을 발휘합니다.
  • 간결한 코드: 복잡한 스키마 설정 없이 직관적으로 에이전트 루프를 구현하고 싶을 때 추천합니다.

이런 분들은 Pydantic AI를 선택하세요

  • 엄격한 데이터 제어: 서비스 운영 환경에서 AI가 내놓는 답변의 형태와 규격이 완벽하게 유지되어야 할 때 필수적입니다.
  • 예외 처리와 안정성: 데이터 검증 오류를 스스로 잡아내고 다시 시도하는 튼튼한 에러 제어 흐름이 필요할 때 빛을 발합니다.
  • 기존 시스템 인터페이스: 이미 견고하게 짜여 있는 비즈니스 로직이나 대규모 파이썬 백엔드에 에이전트를 안전하게 통합하고 싶을 때 적합합니다.

요약하자면, 자유롭고 유연한 코드 실행 비서가 필요하다면 smolagents를, 빈틈없이 규칙을 잘 따르는 든든한 데이터 처리 가이드가 필요하다면 Pydantic AI를 고르시면 됩니다. 여러분의 다음 프로젝트 성격에 맞춰 지금 바로 시작해 보세요!

지금 바로 시작해 보세요!

인공지능 에이전트를 만든다고 하면 거대하고 복잡한 시스템부터 떠올리기 쉽습니다. 하지만 우리가 살펴본 것처럼, 가벼운 도구를 사용하면 생각보다 훨씬 쉽고 재미있게 나만의 에이전트를 빌드할 수 있습니다.

지금 당장 거창한 프로그램 전체를 만들 필요는 전혀 없습니다. 이메일 자동 분류나 매일 아침 뉴스를 요약해 주는 아주 소소한 일상 업무부터 하나씩 직접 자동화해 보세요.

직접 코드를 적어보고 에이전트가 내 명령에 따라 움직이는 모습을 눈으로 확인하는 것만큼 확실한 배움은 없습니다. 여러분의 매일을 더 편리하게 만들어 줄 첫 번째 에이전트 만들기에 오늘 바로 도전해 보시기 바랍니다!

(Edited)