Pydantic AI: 프로덕션 가이드 (Hello World 그 이상)

Pydantic AI: 프로덕션 가이드 (Hello World 그 이상)

원시 LLM 출력은 애플리케이션을 망가뜨립니다. JSON을 요청하면 마크다운이 돌아오고, 1에서 10 사이의 숫자를 요청하면 "물론이죠! 여기 숫자가 있습니다: seven."이라는 답변이 옵니다. LLM API로 실제 무언가를 만들어본 적이 있다면, 자신의 커리어 선택을 의심하게 만드는 방어적 파싱 코드를 작성해 본 경험이 있을 것입니다. Pydantic AI는 이를 해결합니다. 이는 Pydantic과 FastAPI 뒤의 동일한 팀이 구축한 타입 안전한 에이전트 프레임워크입니다. 이를 "AI 에이전트를 위한 FastAPI"라고 생각하세요. Python 타입 힌트로 원하는 것을 정의하면, 프레임워크가 검증, 재시도 및 도구 호출을 처리합니다.

이 Pydantic AI 가이드는 첫 번째 LLM 호출을 이미 실행해보았고 프로덕션 패턴을 원하는 개발자를 위해 작성되었습니다. 깨지지 않는 구조화된 출력, 테스트 가능한 에이전트를 위한 의존성 주입, 그리고 날씨 API 이상의 실제 세계 도구를 다룹니다. 끝까지 읽으면 도구, DI, 스트리밍 및 테스트가 포함된 작동하는 에이전트를 갖게 될 것입니다.

한눈에 보는 Pydantic AI

주목할 만한 기능은 구조화된 출력(Pydantic 모델로 검증됨), 의존성 주입(FastAPI의 Depends와 유사), 그리고 TestModel(API 호출 없이 테스트를 위한 모의 LLM)입니다. LangChain에서 넘어와 "더 깔끔한 것이 있을까?"라고 wondering 중이라면, 이것이 정답일 가능성이 높습니다.

설치 및 첫 번째 에이전트

# Install with OpenAI support (swap openai for anthropic, google, etc.)
pip install "pydantic-ai[openai]"

# Set your API key
export OPENAI_API_KEY="sk-..."

5줄로 작성하는 첫 번째 에이전트:

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o", system_prompt="You are a helpful assistant.")

result = agent.run_sync("What's the capital of France?")
print(result.output)  # "Paris"

끝입니다. Agent는 모델을 감싸고, run_sync는 프롬프트를 보내고 결과를 반환합니다. 여기서 result.output은 일반 문자열이지만, 곧 바뀔 것입니다.

구조화된 출력, Pydantic AI가 존재하는 이유

これが 핵심 기능입니다. LLM으로부터 문자열을 받아서 유효한 JSON인지 희망하며 기도하는 대신, Pydantic 모델을 정의하면 에이전트가 검증된 Python 객체를 반환합니다.

이전: 원시 LLM 출력

# The old way -- hope for the best
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Review the movie Inception. Return JSON with title, rating (1-10), summary."}]
)
# response.choices[0].message.content is a string
# Maybe it's JSON. Maybe it has markdown code fences. Maybe rating is "eight".
# You're on your own.

이후: Pydantic AI로 구조화

from pydantic import BaseModel
from pydantic_ai import Agent

class MovieReview(BaseModel):
    title: str
    rating: int  # Guaranteed to be an int, not "eight"
    summary: str
    recommended: bool

agent = Agent("openai:gpt-4o", result_type=MovieReview)

result = agent.run_sync("Review the movie Inception")
review = result.output  # This is a MovieReview instance, not a string

print(f"{review.title}: {review.rating}/10")
print(f"Recommended: {review.recommended}")
print(review.summary)

차이는 밤과 하늘만큼 큽니다. result.output은 실제 MovieReview 객체입니다. 만약 LLM이 rating: 8 대신 rating: "eight"를 반환한다면, Pydantic의 검증 기능이 이를 잡아냅니다. 다양한 제공업체에서 이것이 어떻게 작동하는지에 대한 자세한 내용은 LLM 제공업체 간 구조화된 출력 가이드를 참조하세요.

검증이 실패할 때 발생하는 일

다른 튜토리얼에서는 보여주지 않는 부분입니다. LLM이 실수했을 때 무슨 일이 일어날까요?

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class StrictReview(BaseModel):
    title: str
    rating: int = Field(ge=1, le=10)  # Must be 1-10
    pros: list[str] = Field(min_length=2)  # At least 2 pros

agent = Agent("openai:gpt-4o", result_type=StrictReview)

# If the LLM returns rating=15 or only 1 pro:
# 1. Pydantic validation fails
# 2. The error message is sent BACK to the LLM
# 3. The LLM tries again with the corrected output
# 4. This repeats up to the retry limit
result = agent.run_sync("Review the movie Inception")

이 피드백 기반 재시도 루프는 Pydantic AI의 킬러 기능입니다. LLM은 자체 검증 오류로부터 학습합니다. 재시도 로직을 직접 작성할 필요가 없으며, 프레임워크가 이를 처리합니다.

판단: 구조화된 출력은 원시 API 호출보다 Pydantic AI를 사용해야 하는 단일 최고의 이유입니다. 손으로 LLM JSON을 파싱하고 있다면 즉시 중단하세요.

도구 및 함수 호출

도구를 사용하면 에이전트가 실제 데이터를 얻기 위해 Python 함수를 호출할 수 있습니다. LLM이 사실을 hallucination(환각)하는 대신, 데이터베이스를 쿼리하거나 문서를 검색하거나 API를 호출할 수 있습니다.

도구 등록

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o")

@agent.tool
async def search_docs(query: str) -> str:
    """Search the documentation for relevant articles."""
    # Your actual search logic here
    results = await doc_search_engine.search(query, limit=5)
    return "\n".join(r.title + ": " + r.snippet for r in results)

@agent.tool 데코레이터는 함수를 등록합니다. Pydantic AI는 함수의 타입 힌트와 docstring을 읽어 LLM에게 도구가 무엇을 하고, 어떤 인수를 받으며, 무엇을 반환하는지 알려줍니다. 수동 스키마 작성이 필요 없습니다. 타입 힌트가 바로 스키마입니다. LLM 함수 호출이 내부적으로 어떻게 작동하는지에 대한 배경 지식은 전용 가이드를 참조하세요.

RunContext: 도구에 데이터 전달

이것이 Pydantic AI가 다른 프레임워크와 차별화되는 지점입니다. RunContext를 사용하면 전역 상태 없이 런타임 데이터(데이터베이스 연결, 사용자 정보, API 클라이언트)를 도구에 전달할 수 있습니다.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class SupportDeps:
    customer_id: str
    db_connection: DatabaseConnection

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

@agent.tool
async def get_order_history(ctx: RunContext[SupportDeps], limit: int = 5) -> str:
    """Fetch recent orders for the current customer."""
    orders = await ctx.deps.db_connection.query(
        "SELECT * FROM orders WHERE customer_id = $1 ORDER BY date DESC LIMIT $2",
        ctx.deps.customer_id, limit
    )
    return format_orders(orders)

ctx.deps는 도구가 런타임에 전달한 모든 것에 접근할 수 있게 해줍니다. 도구는 전역 데이터베이스 연결을 가져오는(import) 것이 아니라, 하나를 수신합니다. 이것이 의존성 주입이며, 에이전트를 테스트 가능하게 만드는 요소입니다.

실제 세계 도구 예제

@agent.tool
async def run_sql_query(ctx: RunContext[SupportDeps], sql: str) -> str:
    """Run a read-only SQL query against the analytics database.
    Only SELECT queries are allowed."""
    if not sql.strip().upper().startswith("SELECT"):
        return "Error: only SELECT queries are allowed"
    results = await ctx.deps.db_connection.fetch(sql)
    return json.dumps(results, default=str)

판단: 타입 힌트가 무거운 일을 처리해주기 때문에 Pydantic AI의 도구 호출은 다른 어떤 프레임워크보다 깔끔합니다. 타입 주석이 있는 일반 Python 함수를 작성하면 됩니다. 나머지는 프레임워크가 알아서 처리합니다.

의존성 주입, LangChain이 가지고 싶어 했던 기능

FastAPI의 Depends를 사용해 본 적이 있다면 Pydantic AI의 DI 시스템을 이미 이해하고 있을 것입니다. 만약 사용하지 않았다면, 요약하자면 다음과 같습니다. 에이전트가 필요한 것(전역 데이터베이스 연결, API 클라이언트, 설정)을 직접 가져가는 대신, 런타임에 모든 것을 전달합니다.

의존성 정의

from dataclasses import dataclass
from pydantic_ai import Agent

@dataclass
class AppDeps:
    db: AsyncDatabasePool
    search_client: SearchAPIClient
    current_user: User

agent = Agent(
    "openai:gpt-4o",
    deps_type=AppDeps,
    system_prompt="You are a customer support agent."
)

도구에서 의존성 사용

@agent.tool
async def lookup_account(ctx: RunContext[AppDeps]) -> str:
    """Look up the current user's account details."""
    account = await ctx.deps.db.fetchrow(
        "SELECT * FROM accounts WHERE user_id = $1",
        ctx.deps.current_user.id
    )
    return json.dumps(account, default=str)

# Run with real dependencies
result = await agent.run(
    "What's my account status?",
    deps=AppDeps(db=real_db, search_client=real_search, current_user=user)
)

DI가 에이전트를 테스트 가능하게 만드는 이유

이것이 진정한 보상입니다. LangChain에서는 컨텍스트를 체인 kwargs나 클로저를 통해 전달했으며, 표준 패턴이 없었습니다. Pydantic AI에서는 실제 의존성을 테스트 더블(test doubles)로 교체하는 것이 매우 간단합니다.

# In your test file
from pydantic_ai import Agent
from your_app import agent, AppDeps

async def test_account_lookup():
    mock_deps = AppDeps(
        db=MockDatabase({"user_123": {"status": "active", "plan": "pro"}}),
        search_client=MockSearch(),
        current_user=User(id="user_123")
    )
    result = await agent.run("What's my account status?", deps=mock_deps)
    assert "active" in result.output
    assert "pro" in result.output

몽키 패칭(monkey-patching) 없음. 전역 import mocking 없음. 단순히 다른 deps를 전달하면 됩니다.

판단: 의존성 주입이 경험 많은 Python 개발자들이 Pydantic AI를 선호하는 이유입니다. FastAPI의 영향력이 드러나는 부분입니다.

모델 제공업체, OpenAI, Anthropic, Gemini, Ollama

Pydantic AI는 모델에 구애받지 않습니다(model-agnostic). 제공업체 전환은 한 줄 변경으로 가능합니다.

# OpenAI
agent = Agent("openai:gpt-4o")

# Anthropic
agent = Agent("anthropic:claude-sonnet-4-20250514")

# Google Gemini
agent = Agent("google-gla:gemini-2.0-flash")

# Local Ollama
agent = Agent("ollama:llama3.1")

도구, 구조화된 출력, DI 등 다른 모든 것은 동일하게 유지됩니다. 모델을 변경해도 비즈니스 로직은 변하지 않습니다.

판단: 모델에 구애받지 않는 설계意味着 당신은 하나의 제공업체에 잠기지 않습니다. 편의를 위해 OpenAI로 시작하고, Anthropic으로 벤치마크하며, 로컬 개발에는 Ollama를 사용하세요.

스트리밍 응답

채팅 UI 및 실시간 애플리케이션에는 스트리밍이 필수적입니다. Pydantic AI는 타입 안전성을 유지하면서 이를 지원합니다.

from pydantic_ai import Agent
from pydantic import BaseModel

class AnalysisResult(BaseModel):
    summary: str
    sentiment: str
    confidence: float

agent = Agent("openai:gpt-4o", result_type=AnalysisResult)

async def stream_analysis(text: str):
    async with agent.run_stream(f"Analyze this text: {text}") as stream:
        async for partial in stream.stream_structured():
            # partial is a partially-validated AnalysisResult
            print(f"Streaming: {partial}")

        # Final result is fully validated
        result = await stream.get_output()
        print(f"Final: {result.summary} ({result.confidence:.0%} confident)")

이는 FastAPI의 StreamingResponse와 완벽하게 어울리며, 같은 생태계와 같은 패턴을 공유합니다. Pydantic AI 에이전트 문서에는 stream_text()를 사용한 텍스트 전용 스트리밍을 포함한 고급 스트리밍 옵션을 다루고 있습니다.

Pydantic AI vs LangGraph vs OpenAI Agents SDK

여기까지 읽으셨다면 아마도 "Pydantic AI와 LangGraph 중 무엇을 사용해야 할까?"라고 묻고 있을 것입니다. 솔직한 답변: 이들은 서로 다른 문제를 해결하며, 둘 다 사용할 수 있습니다.

기능 비교 표

각각을 사용해야 할 때

Pydantic AI 선택: 깔끔하고 타입 안전한 에이전트 코드를 원할 때. 도구(고객 지원 봇, 데이터 추출, 코드 검토 에이전트)가 있는 단일 에이전트 작업과 테스트 가능성이 중요한 상황에 이상적입니다. 팀이 이미 FastAPI와 Pydantic을 사용한다면 학습 곡선은 거의 평평합니다.

LangGraph 선택: 조건부 분기, 인간 승인(human-in-the-loop), 정교한 상태 관리가 필요한 복잡한 다단계 워크플로우가 필요할 때. LangGraph는 개별 에이전트의 품질보다는 여러 단계를 조율하는 데 탁월합니다. 심층 분석을 위해 LangGraph vs CrewAI vs OpenAI Agents SDK 전체 비교를 참조하세요.

OpenAI Agents SDK 선택: 100% OpenAI 환경이고, 가능한 가장 간단한 설정을 원하며, 다중 제공업체 지원이나 DI가 필요하지 않을 때.

조합 패턴

경험 많은 팀들이 실제로 수행하는 방식은 다음과 같습니다. 개별 에이전트에는 Pydantic AI(깔끔한 코드, 테스트 가능, 타입화된 출력)를 사용하고, 에이전트 간 조율(라우팅, 상태 머신, 조건부 로직)에는 LangGraph를 사용합니다. 이들은 경쟁 관계가 아니라 상호 보완적인 계층입니다.

# Pydantic AI agent -- clean, testable, type-safe
support_agent = Agent("openai:gpt-4o", result_type=SupportResponse, deps_type=SupportDeps)

# LangGraph graph -- orchestrates when to call which agent
graph = StateGraph(SupportState)
graph.add_node("classify", classify_intent)
graph.add_node("support", lambda state: support_agent.run_sync(state["query"]))
graph.add_node("escalate", escalate_to_human)

판단: 깔끔하고 테스트 가능한 에이전트 코드를 위해서는 Pydantic AI를 선택하세요. 복잡한 다단계 워크플로우에는 LangGraph를 선택하세요. 이들은 상호 배타적이지 않습니다.

TestModel로 에이전트 테스트하기

이 섹션은 초보자 가이드와 프로덕션 가이드를 구분합니다. 모든 실제 코드베이스에는 테스트가 필요하며, 에이전트 테스트는 notoriously 어렵습니다. LLM 호출은 느리고, 비싸며, 결정론적이지 않기 때문입니다. Pydantic AI는 해결책을 제공합니다. TestModel.

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic import BaseModel

class SupportResponse(BaseModel):
    answer: str
    confidence: float
    escalate: bool

agent = Agent("openai:gpt-4o", result_type=SupportResponse)

# In tests: swap the real model for TestModel
def test_support_agent():
    with agent.override(model=TestModel()):
        result = agent.run_sync("I need help with billing")
        # TestModel returns valid structured data matching your result_type
        assert isinstance(result.output, SupportResponse)
        assert isinstance(result.output.confidence, float)
        assert isinstance(result.output.escalate, bool)

TestModel은 API 호출 없이 result_type과 일치하는 유효한 데이터를 생성합니다. 비용 제로, 결정론적, 빠름. Pydantic AI 테스트 문서에는 custom 응답을 위한 FunctionModel과 도구 호출 검사를 위한 capture_run_messages와 같은 고급 패턴을 다루고 있습니다.

도구와 DI 함께 테스트하기

def test_order_lookup_tool():
    # Mock dependencies
    mock_deps = SupportDeps(
        customer_id="test-123",
        db_connection=MockDB(orders=[{"id": "ord-1", "status": "shipped"}])
    )

    with agent.override(model=TestModel()):
        result = agent.run_sync(
            "Where is my order?",
            deps=mock_deps
        )
        assert isinstance(result.output, SupportResponse)

API 호출 없음. 불안정한 테스트 없음. 비용 없음. CI/CD에서 나머지 테스트 스위트와 함께 실행하세요.

이것은 전체 SERP에서 가장 큰 콘텐츠 격차입니다. 다른 Pydantic AI 가이드는 테스트를 다루지 않습니다. 프로덕션을 위해 에이전트를 구축한다면, 이것이 당신이 필요한 것입니다.

관찰 가능성, 5분 만에 Logfire 통합

프로덕션 에이전트에는 AI 관찰 가능성이 필요합니다. 모든 LLM 호출, 도구 호출, 지연 시간, 토큰 수 및 비용을 확인하고 싶을 것입니다. Pydantic AI는 Pydantic 팀의 관찰 가능성 플랫폼인 Logfire(OpenTelemetry 기반)와 네이티브로 통합됩니다.

import logfire
from pydantic_ai import Agent

logfire.configure()  # Uses LOGFIRE_TOKEN env var
logfire.instrument_pydantic_ai()

agent = Agent("openai:gpt-4o", result_type=MovieReview)
# Every run is now traced automatically
result = agent.run_sync("Review Inception")

세 줄이면 됩니다. 전송된 프롬프트, 모델 응답, 도구 호출(있는 경우), 검증 통과/실패, 재시도, 지연 시간 및 예상 비용을 보여주는 전체 트레이스를 얻을 수 있습니다. Logfire가 마음에 들지 않는다면, Langfuse는 프롬프트 진화 과정을 추적하기 위한 컨텍스트 엔지니어링 지원을 갖춘 견고한 오픈 소스 대안입니다.

FAQ

Pydantic AI란 무엇이며 LangChain과 어떻게 다른가요?

Pydantic AI는 Python 타입 힌트가 검증, 도구 스키마 및 의존성 주입을 주도하는 타입 안전한 에이전트 프레임워크입니다. LangChain은 LLM 호출을 연결하는 데 중점을 둔 더 큰 프레임워크입니다. 주요 차이점: Pydantic AI는 프레임워크 수준에서 출력을 검증하고 테스트 가능성을 위한 내장 의존성 주입을 제공하는 반면, LangChain은 기본적으로 둘 다 제공하지 않습니다.

Pydantic AI로 타입 안전한 AI 에이전트를 어떻게 구축하나요?

출력에 대한 Pydantic BaseModel을 정의하고, 이를 Agent의 result_type으로 전달한 후 run_sync() 또는 run()을 호출하세요. 에이전트는 원시 문자열이 아닌 모델의 검증된 인스턴스를 반환합니다. 완전한 예제는 구조화된 출력 섹션을 참조하세요.

프로덕션 에이전트에 Pydantic AI와 LangGraph 중 무엇을 사용해야 할까요?

타입 안전성, 테스트 가능성 및 깔끔한 코드가 중요한 개별 에이전트에는 Pydantic AI를 사용하세요. 조건부 라우팅이 있는 복잡한 다단계 워크플로우를 조율하려면 LangGraph를 사용하세요. 많은 팀이 LangGraph 조율 계층 내에서 Pydantic AI 에이전트를 사용하는 방식으로 둘 다 사용합니다.

Pydantic AI는 도구 호출과 의존성 주입을 어떻게 처리하나요?

함수에 @agent.tool로 데코레이트하면 Pydantic AI는 타입 힌트를 읽어 도구 스키마를 생성합니다. DI를 위해서는 Agent에 deps_type을 설정하고 도구에서 RunContext[YourDeps]를 받으세요. 런타임 의존성(DB 연결, API 클라이언트)은 전역 상태 없이 흐릅니다.

Pydantic AI 에이전트에 스트리밍을 어떻게 추가하나요?

agent.run() 대신 agent.run_stream()을 사용하세요. 이는 stream_structured() 또는 stream_text()를 통해 부분 결과를 yield하는 async 컨텍스트 매니저를 반환합니다. 최종 결과는 여전히 result_type에 대해 완전히 검증됩니다.

2026년에 Pydantic AI는 프로덕션 준비가 되었나요?

예. 2025년 9월에 버전 1.0이 출시되었으며 API 안정성 약속이 포함되어 있습니다. 이는 데이터 검증을 위한 가장 많이 다운로드된 Python 라이브러리인 Pydantic 팀의 지원을 받으며, 현재 정기적인 업데이트가 이루어지는 v1.74.0입니다.

Ollama 및 로컬 모델과 함께 Pydantic AI를 사용할 수 있나요?

예. Agent("ollama:llama3.1")를 사용하고 Ollama가 로컬에서 실행 중인지 확인하세요. ollama 제공업체 추가 기능을 설치하세요: pip install "pydantic-ai[ollama]". 구조화된 출력과 도구는 클라우드 제공업체와 동일하게 작동합니다.

Pydantic AI 에이전트를 어떻게 테스트하나요?

API 호출 없이 result_type과 일치하는 유효한 구조화 데이터를 생성하는 모의 모델인 TestModel을 사용하세요. 테스트를 agent.override(model=TestModel())로 감싸고 출력에 대한 어설션을 실행하세요. 완전한 pytest 예제는 테스트 섹션을 참조하세요.

Pydantic AI는 FastAPI와 함께 작동하나요?

완벽하게 작동합니다. 이들은 동일한 의존성 주입 철학을 공유하며 동일한 팀에서 구축되었습니다. FastAPI 엔드포인트 내에서 Pydantic AI 에이전트를 사용하고, 유형을 공유하며, StreamingResponse를 통해 에이전트 응답을 스트리밍할 수 있습니다.

Pydantic AI와 OpenAI Agents SDK의 차이점은 무엇인가요?

Pydantic AI는 모델에 구애받지 않으며(OpenAI, Anthropic, Gemini, Ollama 등에서 작동), 의존성 주입, 테스트용 TestModel 및 Pydantic 검증을 갖추고 있습니다. OpenAI Agents SDK는 더 단순하지만 OpenAI 모델에 고정되어 있으며 DI와 내장 테스트가 부족합니다. 유연성을 원하면 Pydantic AI를 선택하세요. 가능한 가장 간단한 OpenAI 전용 설정을 원하면 OpenAI Agents SDK를 선택하세요.

주요 요약 및 다음 단계

구조화된 출력이 있는 작은 에이전트로 시작하세요. 도구를 추가하세요. 의존성을 추가하세요. TestModel로 테스트를 작성하세요. 이것이 프로덕션 경로이며, 이제 이를 걷기 위해 필요한 모든 것을 갖추었습니다.

더 깊이 들어가기 위해 공식 Pydantic AI 문서와 GitHub 저장소는 훌륭합니다. 프레임워크는 빠르게 움직이므로 변경 로그(changelog)를 북마크하세요.

출처

• Pydantic AI, 공식 문서
• Pydantic AI 의존성 문서
• Pydantic AI 테스트 문서
• Pydantic AI v1 출시 발표
• Logfire AI 관찰 가능성
• pydantic/pydantic-ai, GitHub 저장소