DEV Community

Cover image for PydanticAI란 무엇인가? 타입 안전 파이썬 에이전트 프레임워크 완벽 가이드
Rihpig
Rihpig

Posted on • Originally published at apidog.com

PydanticAI란 무엇인가? 타입 안전 파이썬 에이전트 프레임워크 완벽 가이드

LLM 기능을 프로덕션에 배포한 뒤 잘못된 형식의 JSON 때문에 파이프라인이 깨진 적이 있다면, PydanticAI를 검토할 만합니다. Pydantic 팀이 만든 Python 에이전트 프레임워크로, 에이전트 출력과 도구 호출을 Pydantic 모델로 검증하는 데 초점을 둡니다. 이 글에서는 PydanticAI의 핵심 개념, 기본 구현 방식, 그리고 LangGraph 같은 Python 에이전트 프레임워크와의 차이를 정리합니다.

오늘 Apidog를 사용해 보세요

PydanticAI란 무엇인가

PydanticAI는 Python용 오픈 소스, 공급업체 독립적인 에이전트 프레임워크입니다. Pydantic Validation 및 Pydantic Logfire를 개발하는 팀이 유지 관리하며, 목표는 에이전트 개발에 “FastAPI 같은” 타입 안전성과 개발 경험을 제공하는 것입니다.

Pydantic AI

PydanticAI에서는 다음 세 가지를 명확히 정의합니다.

  • 에이전트가 따라야 할 지침
  • 에이전트가 호출할 수 있는 도구
  • 에이전트가 반환해야 하는 출력 구조

프레임워크는 모델 호출을 실행하고, 결과를 Pydantic 모델로 검증합니다. 모델이 유효하지 않은 값을 반환하면 검증 오류를 기반으로 재시도합니다.

설치는 다음 중 하나로 시작할 수 있습니다.

pip install pydantic-ai
Enter fullscreen mode Exit fullscreen mode

또는:

uv add pydantic-ai
Enter fullscreen mode Exit fullscreen mode

PydanticAI는 여러 베타 버전을 거쳐 2026년 6월 23일 안정적인 v2.0.0 릴리스에 도달했습니다. v2는 도구, 훅, 지침, 모델 설정을 재사용 가능한 단위로 구성하는 하네스 우선 설계를 지향합니다.

왜 타입 안전성이 에이전트에게 중요한가

LLM은 비결정적입니다. 같은 프롬프트를 두 번 실행해도 서로 다른 형태의 응답을 받을 수 있습니다. 채팅 UI에서는 큰 문제가 아닐 수 있지만, 모델 출력을 다음과 같은 코드에 연결하면 문제가 됩니다.

  • 데이터베이스 쓰기
  • REST API 호출
  • 결제 또는 청구 계산
  • 사용자 권한 판단
  • 자동화 워크플로 실행

대표적인 실패 사례는 다음과 같습니다.

{
  "category": "billing",
  "priority": "high"
}
Enter fullscreen mode Exit fullscreen mode

코드는 priority를 정수로 기대하지만, 모델은 문자열을 반환할 수 있습니다. 또는 필드를 누락하거나 JSON 앞뒤에 설명 문장을 붙일 수도 있습니다.

PydanticAI는 이 문제를 출력 계약으로 해결합니다. 출력 타입을 Pydantic 모델로 정의하면, 에이전트 결과는 해당 모델과 일치해야 합니다. 유효하지 않으면 프레임워크가 LLM에 오류를 전달하고 다시 생성하도록 요청합니다.

즉, 하위 코드는 문자열을 파싱하는 대신 검증된 Python 객체를 받습니다.

도구 호출도 동일합니다. 모델이 도구를 호출할 때 PydanticAI는 함수의 타입 힌트를 기준으로 인수를 검증합니다. 잘못된 인수는 비즈니스 로직까지 도달하지 않습니다.

핵심 개념

PydanticAI로 에이전트를 만들 때 주로 다루는 개념은 다음 다섯 가지입니다.

  1. 에이전트
  2. 타입이 지정된 출력
  3. 도구
  4. 종속성
  5. 모델 공급업체 및 스트리밍

1. 에이전트 만들기

Agent 클래스가 기본 진입점입니다. 모델 식별자와 지침을 전달해 에이전트를 생성합니다.

from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Be concise, reply with one sentence.',
)

result = agent.run_sync('Where does "hello world" come from?')
print(result.output)
Enter fullscreen mode Exit fullscreen mode

모델을 바꾸려면 모델 문자열만 변경하면 됩니다.

agent = Agent(
    'openai:gpt-4o',
    instructions='Be concise, reply with one sentence.',
)
Enter fullscreen mode Exit fullscreen mode

이 방식은 코드 구조를 공급업체에 강하게 묶지 않도록 해줍니다.

2. 타입이 지정된 출력 사용하기

구조화된 응답이 필요하면 Pydantic 모델을 정의하고 output_type으로 전달합니다.

from pydantic import BaseModel
from pydantic_ai import Agent

class SupportTicket(BaseModel):
    category: str
    priority: int
    summary: str

agent = Agent(
    'openai:gpt-4o',
    output_type=SupportTicket,
)

result = agent.run_sync('My payment failed three times today.')

ticket = result.output

print(ticket.category)
print(ticket.priority)
print(ticket.summary)
Enter fullscreen mode Exit fullscreen mode

이제 result.output은 단순 문자열이 아니라 SupportTicket 객체입니다.

예를 들어 모델이 다음처럼 반환하면:

{
  "category": "payment",
  "priority": "urgent",
  "summary": "Payment failed three times today."
}
Enter fullscreen mode Exit fullscreen mode

priority가 int가 아니므로 검증이 실패합니다. PydanticAI는 오류를 모델에 전달하고 올바른 구조로 다시 생성하도록 요청합니다.

실무에서는 출력 모델을 더 구체적으로 만들 수 있습니다.

from typing import Literal
from pydantic import BaseModel, Field

class SupportTicket(BaseModel):
    category: Literal['billing', 'technical', 'account']
    priority: int = Field(ge=1, le=5)
    summary: str
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 다음 조건을 강제할 수 있습니다.

  • category는 허용된 값 중 하나여야 함
  • priority는 1부터 5 사이의 정수여야 함
  • summary는 반드시 있어야 함

3. 도구 등록하기

도구는 에이전트가 외부 시스템과 상호작용할 수 있게 합니다.

예:

  • 데이터베이스 조회
  • REST API 호출
  • 내부 서비스 호출
  • 계산 실행
  • 사용자 정보 조회

PydanticAI에서는 @agent.tool 데코레이터로 도구를 등록합니다.

from pydantic_ai import Agent, RunContext

agent = Agent('openai:gpt-4o', deps_type=str)

@agent.tool
async def get_user_balance(ctx: RunContext[str], account_id: str) -> float:
    """Return the current balance for an account."""
    return await lookup_balance(ctx.deps, account_id)
Enter fullscreen mode Exit fullscreen mode

여기서 중요한 점은 다음과 같습니다.

  • account_id: str 타입 힌트가 도구 스키마에 사용됩니다.
  • 모델이 도구를 호출할 때 인수가 검증됩니다.
  • ctx.deps를 통해 외부 종속성을 사용할 수 있습니다.

예를 들어 실제 구현에서는 ctx.deps에 API 기본 URL, 데이터베이스 클라이언트, 인증 토큰 등을 넣을 수 있습니다.

4. 종속성 주입 사용하기

프로덕션 에이전트는 보통 외부 리소스가 필요합니다.

  • HTTP 클라이언트
  • 데이터베이스 연결
  • 현재 사용자 정보
  • API 키
  • 설정 객체

PydanticAI는 deps_type과 RunContext로 종속성 주입을 처리합니다.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class AppDeps:
    api_base_url: str
    api_key: str

agent = Agent(
    'openai:gpt-4o',
    deps_type=AppDeps,
)

@agent.tool
async def get_order_status(ctx: RunContext[AppDeps], order_id: str) -> str:
    """Return the status of an order."""
    # 실제 구현에서는 ctx.deps.api_base_url 및 ctx.deps.api_key 사용
    return await fetch_order_status(
        base_url=ctx.deps.api_base_url,
        api_key=ctx.deps.api_key,
        order_id=order_id,
    )

deps = AppDeps(
    api_base_url='https://api.example.com',
    api_key='secret',
)

result = agent.run_sync(
    'Check order A123.',
    deps=deps,
)
Enter fullscreen mode Exit fullscreen mode

테스트에서는 실제 종속성을 가짜 객체로 교체할 수 있습니다.

test_deps = AppDeps(
    api_base_url='https://mock.example.com',
    api_key='test-key',
)
Enter fullscreen mode Exit fullscreen mode

이 구조는 에이전트 로직과 외부 시스템 연결을 분리하는 데 유용합니다.

5. 모델 공급업체와 스트리밍

PydanticAI는 여러 모델 공급업체를 지원합니다.

  • OpenAI
  • Anthropic
  • Gemini
  • DeepSeek
  • Grok
  • Cohere
  • Mistral
  • Perplexity
  • Azure AI Foundry
  • Amazon Bedrock
  • 자체 호스팅 모델

공급업체 전환은 일반적으로 모델 문자열 변경으로 처리합니다.

Agent('openai:gpt-4o')
Enter fullscreen mode Exit fullscreen mode 
Agent('anthropic:claude-sonnet-4-6')
Enter fullscreen mode Exit fullscreen mode

또한 PydanticAI는 데이터가 도착하는 대로 구조화된 출력을 스트리밍할 수 있습니다. 이를 통해 부분 결과를 렌더링하면서도 타입 검증 흐름을 유지할 수 있습니다.

Pydantic Logfire와의 연계도 중요합니다. 실행 추적, 디버깅, 비용 추적 같은 관찰 가능성 기능을 함께 사용할 수 있습니다.

PydanticAI와 다른 Python 에이전트 프레임워크 비교

하나의 “최고” 프레임워크가 있는 것은 아닙니다. 각 프레임워크는 다른 문제를 최적화합니다.

프레임워크 핵심 강점 적합한 경우
PydanticAI 타입 안전하고 유효성이 검증된 출력 및 도구 인수 프로덕션 신뢰성과 타입 지정 데이터 흐름이 중요할 때
LangGraph 명시적인 상태 저장 그래프 및 제어 흐름 장기 실행, 분기, 다단계 워크플로가 필요할 때
Google ADK Google 생태계 내 다중 에이전트 오케스트레이션 Gemini 및 Vertex AI 통합이 중요할 때
OpenAI Agents SDK 핸드오프 기능이 있는 OpenAI 통합 OpenAI 우선 스택에서 빠르게 구축할 때

PydanticAI의 강점은 검증 계층입니다. 에이전트 출력이 다른 시스템으로 전달된다면, 출력이 Pydantic 모델과 일치한다는 보장이 런타임 오류를 줄여줍니다.

LangGraph는 상태 머신과 복잡한 제어 흐름에 더 적합합니다. 여러 단계, 분기, 재시도, 상태 전이가 명확한 워크플로라면 LangGraph가 더 직접적인 제어 수단을 제공합니다.

OpenAI Agents SDK는 OpenAI 중심 스택에서 빠르게 시작하기 좋습니다. 에이전트 핸드오프나 MCP 서버 지원 같은 기능이 필요할 때 자연스러운 선택입니다.

혼합해서 사용할 수도 있습니다. 예를 들어 LangGraph로 전체 워크플로를 제어하고, 특정 노드에서 PydanticAI를 사용해 검증된 구조화 출력을 생성할 수 있습니다.

PydanticAI를 사용해야 하는 경우

다음 조건에 해당하면 PydanticAI가 잘 맞습니다.

  • 에이전트 출력이 채팅 UI가 아니라 실제 코드로 들어간다.
  • 출력 형태가 정확해야 한다.
  • Pydantic 모델로 응답 구조를 강제하고 싶다.
  • IDE와 타입 체커가 에이전트 결과를 이해해야 한다.
  • 이미 코드베이스에서 Pydantic 또는 FastAPI를 사용하고 있다.
  • 모델 공급업체를 바꿀 가능성이 있다.
  • Logfire 기반 관찰 가능성이 필요하다.

반대로 다음 경우에는 다른 도구가 더 적합할 수 있습니다.

  • 복잡한 상태 머신이 필요하다.
  • 워크플로가 여러 분기와 장기 실행 상태를 가진다.
  • 에이전트 간 오케스트레이션이 핵심 요구사항이다.
  • 그래프 기반 제어 흐름이 더 중요하다.

에이전트 뒤의 API 테스트 및 모킹

PydanticAI 에이전트는 의존하는 API만큼만 안정적입니다. 모든 실행은 LLM 공급업체를 호출하며, 대부분의 유용한 에이전트는 내부 REST API나 서드파티 도구도 호출합니다.

이 지점에서 다음 문제가 발생할 수 있습니다.

  • API 응답 형태가 예상과 다름
  • 필수 필드 누락
  • 인증 실패
  • 스트리밍 형식 불일치
  • 공급업체 속도 제한
  • 테스트 중 불필요한 토큰 비용 발생

PydanticAI는 모델의 출력은 검증할 수 있지만, 여러분이 호출하는 업스트림 API가 올바른 응답을 반환하는지는 직접 보장하지 않습니다.

Apidog API testing

이때 Apidog를 사용할 수 있습니다. Apidog는 에이전트 프레임워크가 아니라, 에이전트가 통신하는 API를 테스트하고 모의하는 API 플랫폼입니다.

실무에서 사용할 수 있는 방식은 다음과 같습니다.

1. LLM 또는 도구 엔드포인트 모의하기

개발 중에는 실제 공급업체 대신 결정적인 응답을 반환하는 모의 API를 사용할 수 있습니다.

이렇게 하면 다음을 줄일 수 있습니다.

  • 반복 테스트 중 토큰 비용
  • 공급업체 rate limit 문제
  • 비결정적 응답으로 인한 테스트 불안정성

2. REST 응답 형태 단언하기

@agent.tool 함수가 REST API를 호출한다면, 먼저 API 응답 구조를 검증해야 합니다.

API 단언을 사용하면 다음을 API 계층에서 확인할 수 있습니다.

  • 필수 필드 존재 여부
  • 응답 타입
  • 상태 코드
  • 중첩 객체 구조
  • 에러 응답 형식

이렇게 하면 에이전트 실행 중간이 아니라 API 테스트 단계에서 문제를 잡을 수 있습니다.

3. 환경별 키와 기본 URL 관리하기

로컬, 스테이징, CI 환경에서 서로 다른 API 키와 기본 URL을 사용해야 한다면 Apidog 환경을 분리해 관리할 수 있습니다.

예:

  • Local
  • Staging
  • Production
  • CI Mock

코드를 바꾸지 않고 환경만 전환하면 테스트 대상도 바꿀 수 있습니다.

4. LLM 엔드포인트 직접 검증하기

HTTP로 LLM 공급업체를 직접 호출한다면, 에이전트에 연결하기 전에 ChatGPT API 테스트를 통해 다음을 확인할 수 있습니다.

  • 인증 헤더
  • 요청 본문
  • 스트리밍 응답
  • 도구 호출 형식
  • 에러 응답

Apidog는 PydanticAI의 대안이 아닙니다. PydanticAI가 에이전트와 타입 검증을 담당한다면, Apidog는 에이전트가 호출하는 API 표면을 테스트하고 모의하는 역할을 합니다.

시작하려면 Apidog를 다운로드하고, 먼저 에이전트 도구 엔드포인트 하나를 모의해보세요.

자주 묻는 질문

PydanticAI는 무료이며 오픈 소스인가요?

네. PydanticAI는 오픈 소스이며 PyPI에서 설치할 수 있습니다.

pip install pydantic-ai
Enter fullscreen mode Exit fullscreen mode

또는:

uv add pydantic-ai
Enter fullscreen mode Exit fullscreen mode

다만 사용하는 LLM 공급업체의 API 비용은 별도로 발생합니다. 개발 중 비용을 줄이려면 매번 실제 모델을 호출하는 대신 테스트 중 API 응답을 모의할 수 있습니다.

PydanticAI는 어떤 모델과 작동하나요?

공급업체 독립적으로 설계되어 있습니다. 문서에는 OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity가 포함되어 있으며, Azure AI Foundry, Amazon Bedrock, 자체 호스팅 모델도 지원 대상으로 나열되어 있습니다.

모델은 Agent 생성자에 문자열로 지정합니다.

Agent('anthropic:claude-sonnet-4-6')
Enter fullscreen mode Exit fullscreen mode

또는:

Agent('openai:gpt-4o')
Enter fullscreen mode Exit fullscreen mode

전환은 일반적으로 이 문자열을 바꾸는 방식으로 처리합니다.

PydanticAI는 LangChain 또는 LangGraph와 어떻게 다른가요?

PydanticAI는 타입 안전성과 검증된 구조화 출력에 집중합니다. Pydantic 모델을 기반으로 출력과 도구 인수를 검증합니다.

LangGraph는 다단계, 분기, 장기 실행 워크플로를 위한 명시적인 상태 저장 그래프에 집중합니다.

정리하면 다음과 같습니다.

  • 출력 형태 보장과 타입 지정 데이터 흐름이 중요하면 PydanticAI
  • 복잡한 상태 머신과 그래프 기반 제어가 중요하면 LangGraph

사용하려면 Pydantic을 알아야 하나요?

기본 개념을 알면 좋습니다. PydanticAI에서는 BaseModel을 상속한 클래스로 데이터 형태를 정의합니다.

from pydantic import BaseModel

class Answer(BaseModel):
    title: str
    confidence: float
Enter fullscreen mode Exit fullscreen mode

FastAPI를 사용해본 적이 있거나 API 테스트용 Python을 다뤄본 적이 있다면 익숙한 방식입니다.

결론

PydanticAI는 에이전트 개발에서 자주 발생하는 문제를 직접 다룹니다. 모델 출력과 도구 호출이 선언한 타입과 일치하는지 검증하고, 유효하지 않으면 재시도합니다.

다음이 중요하다면 PydanticAI를 선택하세요.

  • 프로덕션 신뢰성
  • 구조화된 출력
  • Pydantic 기반 검증
  • 타입 체커와 IDE 지원
  • 공급업체 유연성

반대로 복잡한 그래프 오케스트레이션이 핵심이라면 LangGraph 같은 프레임워크가 더 적합할 수 있습니다.

어떤 에이전트 프레임워크를 사용하든, 에이전트 아래의 API는 별도로 테스트해야 합니다. LLM 및 도구 엔드포인트를 모의하고, 응답 형태를 단언하며, Apidog에서 환경별 키를 관리하면 에이전트를 더 검증된 기반 위에서 실행할 수 있습니다.

Top comments (0)