Pydantic AI는 Python에서 프로덕션급 AI 에이전트를 구축하기 위한 프레임워크다. LLM 응답을 문자열이 아닌 검증된 Pydantic 모델 객체로 받고, 함수를 타입 힌트와 독스트링 기반으로 툴로 등록하며, 런타임 의존성(DB 연결, API 클라이언트 등)을 RunContext로 주입한다. LangChain 같은 기존 프레임워크에 비해 타입 안전성과 테스트 용이성에 집중한 설계다.

핵심 개념

구조화 출력 (Structured Output)

output_type에 Pydantic BaseModel을 지정하면 프레임워크가 LLM 응답을 해당 스키마로 강제 변환하고, 실패 시 자동 재시도한다.

from pydantic import BaseModel
from pydantic_ai import Agent

class JobPosting(BaseModel):
    job_title: str
    required_skills: list[str]
    is_remote: bool

agent = Agent("openai:gpt-4o-mini", output_type=JobPosting)
result = agent.run_sync("...")
posting = result.output  # 검증된 JobPosting 객체

함수 툴 (Function Tools)

@agent.tool_plain 또는 @agent.tool 데코레이터로 Python 함수를 등록한다. LLM이 독스트링과 타입 힌트를 읽어 언제 어떻게 호출할지 결정하므로, 독스트링이 곧 툴 설명서가 된다.

@agent.tool_plain
def get_weather(city: str) -> str:
    """Returns current temperature in Celsius for the given city."""
    ...

의존성 주입 (Dependency Injection)

deps_type으로 의존성 타입을 선언하고, 런타임에 deps= 인자로 인스턴스를 주입한다. @agent.tool에서 RunContext를 통해 접근하며, 테스트 시 mock으로 교체 가능하다.

from pydantic_ai import Agent, RunContext
from dataclasses import dataclass

@dataclass
class MyService:
    db: dict

agent = Agent("openai:gpt-4o-mini", deps_type=MyService)

@agent.tool
def lookup(ctx: RunContext[MyService], key: str) -> str:
    """Look up a value from the service database."""
    return str(ctx.deps.db.get(key))

service = MyService(db={"answer": "42"})
result = agent.run_sync("What is the answer?", deps=service)

내장 기능 (Built-in Capabilities)

capabilities 인자로 웹 검색과 추론 모드를 간단히 추가할 수 있다.

from pydantic_ai.capabilities import WebSearch, Thinking

agent = Agent(
    "openai:gpt-4o-mini",
    capabilities=[Thinking(effort="high"), WebSearch()]
)

타 프레임워크와 비교

지원 모델

"provider:model-name" 형식으로 지정. 프리픽스만 바꾸면 동일 코드로 다른 제공자를 사용할 수 있다.

• openai:gpt-4o-mini — OpenAI
• anthropic:claude-sonnet-4-6 — Anthropic
• google-gla:gemini-2-0-flash — Google

설치

pip install pydantic-ai

Python 3.9 이상 필요. API 키는 환경 변수로 설정한다.

사용 대상

• Python 백엔드 개발자: FastAPI·Django와 함께 타입 안전한 AI 기능을 추가하려는 팀
• ML 엔지니어: 출력 스키마를 엄격하게 관리해야 하는 프로덕션 AI 파이프라인
• LLM 앱 테스터: 에이전트 동작을 격리해 단위 테스트로 검증하려는 개발자

라이선스

MIT

관련 문서

• pydantic-ai-tutorial-agents — Pydantic AI로 구조화 에이전트 구축 단계별 실습
• local-slm — 로컬 소형 언어 모델로 Pydantic AI 에이전트 구동하기

참고 자료

• Building AI Agents in Python with Pydantic AI — Machine Learning Mastery (2026-04-29)
• pydantic/pydantic-ai — GitHub 공식 저장소