Pydantic AI로 Python 에이전트 만들기: 검증부터 운영까지

2026년 10월 17일 개발사의 문서와 저장소 라이선스를 기준으로 확인한 내용입니다. 이 글에서는 성능 순위 대신 출력 검증, 애플리케이션 서비스 접근, 워크플로 제어와 복구를 기준으로 선택을 돕습니다.

Pydantic AI란 무엇인가요?

Pydantic AI는 Pydantic 팀이 만든 Python 에이전트 SDK입니다. 모델, 지침, 호출 가능한 Python 함수, 선택적으로 지정하는 출력 타입을 애플리케이션이 실행할 Agent 객체에 묶습니다. 모델은 응답을 생성하는 시스템이고, SDK는 그 주변의 상호작용을 관리합니다. 현재 개요 문서는 SDK의 더 넓은 범위를 다루지만, 제품 기능을 만들 때 필요한 핵심은 여기에 있습니다.

행동을 예측하기 어려운 협업 상대에게 함수의 입출력 규약을 정해 주는 셈입니다. 애플리케이션은 맥락과 허용된 작업을 제공하고, 정해진 이름의 필드를 갖춘 결과를 요구합니다. 예를 들어 고객 지원 기능이 일반 Python 코드에서 바로 활용할 수 있는 문의 유형과 다음 조치를 반환해야 할 때 유용합니다.

Pydantic AI 에이전트: 재사용할 수 있는 작업 단위

Agent는 작업에 필요한 설정을 담습니다. 실행은 프롬프트와 런타임 의존성을 받아 그 작업을 수행하는 개별 시도입니다. 동기 스크립트에서는 run_sync()를, 비동기 애플리케이션 코드에서는 await agent.run()을 호출할 수 있습니다. 실행이 완료되면 결과의 .output으로 최종 값에 접근합니다. 이 동작은 Agent API 문서에 나와 있습니다.

타입에는 서로 다른 두 가지 역할이 있습니다. 정적 타입 검사는 편집기나 타입 검사기가 Python 코드의 타입 불일치를 찾도록 돕습니다. 런타임 출력 검증은 모델이 반환한 데이터가 선언한 스키마를 따르는지 확인합니다. 어느 쪽도 모호한 고객 문의 자체를 명확하게 바꿔 주지는 않습니다.

Pydantic AI 툴: 애플리케이션 맥락을 활용하는 함수

함수 툴을 등록하면 모델이 구독 정보 조회처럼 코드가 수행할 수 있는 작업을 요청할 수 있습니다. 실행 맥락이 필요한 함수에는 @agent.tool을, 실행 맥락이 필요 없는 함수에는 @agent.tool_plain을 사용합니다. 타입 힌트는 인자를 설명하고, 독스트링은 모델에 툴의 용도를 전달하는 데 쓰입니다. 이것이 툴 스키마로 변환되는 과정은 함수 툴 문서에서 설명합니다.

의존성 주입은 실행에 필요한 서비스를 해당 실행에 전달하는 방식입니다. deps_type=CustomerContext로 예상하는 Python 타입을 선언하고, deps=customer_context로 실제 인스턴스를 전달합니다. 툴은 RunContext[CustomerContext]를 받아 ctx.deps로 그 인스턴스에 접근합니다. 이 맥락에는 인증된 고객 정보, 데이터베이스 연결, API 클라이언트 등을 담을 수 있습니다. 의존성 가이드는 deps_type이 타입 검사를 지원할 뿐, 의존성 객체를 런타임에 검증하지는 않는다고 명시합니다.

SaaS를 개발할 때 얻는 이점은 분명합니다. 모델이 조회를 요청하기 전에 서버에서 고객 계정을 정할 수 있습니다. 다만 접근 권한 검사는 조회 코드에서 처리해야 합니다. 타입이 지정된 맥락으로 데이터베이스 클라이언트를 전달해도 그 클라이언트가 읽을 수 있는 행이 제한되지는 않습니다.

Pydantic AI 구조화 출력은 무엇을 검증하나요?

output_type은 애플리케이션이 받을 결과의 형태를 정의합니다. 타입이 지정된 필드를 갖춘 Python 클래스인 Pydantic BaseModel을 전달하면 Pydantic AI가 스키마를 만들고 생성된 데이터를 검증합니다. 출력 문서에는 dataclass, 리스트, 유니언 등 다른 타입도 지원한다고 나와 있습니다.

세 가지 출력 모드의 차이는 모델에 데이터를 생성하도록 요청하는 방식에 있습니다.

이는 SDK에 문서화된 세 가지 출력 모드이며, 정확도를 세 등급으로 나눈 것이 아닙니다. 모델이 지원하는 방식을 고른 뒤 실제 작업에서 결과를 평가해야 합니다.

검증에 실패하면 그 내용을 모델에 돌려보내 다시 시도하게 할 수 있습니다. 재시도 횟수에는 한도가 있으며, 출력 재시도 한도를 소진하면 UnexpectedModelBehavior가 발생할 수 있습니다. 애플리케이션에는 누락된 정보를 요청하거나 담당자에게 넘기는 등의 실패 처리 경로가 필요합니다. 자세한 내용은 재시도 동작 문서를 참고할 수 있습니다.

Pydantic AI 사용법: 검증된 고객 문의 분류 결과 만들기

에이전트에 변경 권한을 주기 전에, 판단 결과를 담는 작은 읽기 전용 객체부터 만드는 것이 좋습니다. 다음 예제는 문서의 Agent, RunContext, output_type 패턴을 간단한 고객 문의 분류 작업에 적용한 것입니다.

현재 설치 가이드는 Python 3.11 이상을 요구합니다. 가상 환경에서 라이브러리를 설치합니다.

python -m pip install pydantic-ai

사용할 모델에 접근할 수 있는 계정의 OPENAI_API_KEY를 환경 변수로 설정합니다. 아래 코드를 triage.py로 저장한 뒤 python triage.py를 실행합니다. 모델 식별자는 현재 Agent 문서에 나온 것을 사용했습니다. 계정에서 이용할 수 있는 지원 모델로 바꿔도 됩니다.

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

실행에 성공하면 result.output은 Triage 객체가 됩니다. 문의 유형과 우선순위는 선언한 선택지 중 하나여야 하며, model_dump()로 객체를 딕셔너리로 변환할 수 있습니다. 이 예제의 맥락 제공 툴, 타입이 지정된 결과, 잘못된 문의 유형의 거부 동작은 TestModel을 사용해 오프라인으로 확인했습니다. 모델이 생성하는 문구와 분류 정확도는 각자의 실제 사례로 평가해야 합니다.

고객 맥락은 설명을 위한 예시입니다. 실제 제품에서는 인증된 요청과 계정 기록을 바탕으로 구성해야 합니다. 어떤 문의를 긴급으로 분류할지도 정의해야 합니다. 스키마는 유효한 라벨만 나열할 뿐, 긴급 여부를 판단할 정책은 담고 있지 않습니다. 에이전트를 하나 더 추가하는 것보다 이렇게 빠진 업무 규칙을 채우는 일이 더 중요합니다.

Pydantic AI 지원 모델: 제공업체를 바꾸면 동작도 달라집니다

Pydantic AI는 제공업체마다 따로 작성해야 하는 연결 코드를 줄여 주지만, 모델을 바꾸면 동작도 달라집니다. 많은 연결 방식에서 <provider>:<model> 식별자를 사용합니다. 일부는 모델이나 클라이언트를 명시적으로 구성하고, 적절한 인증 정보를 설정하고, 추가 의존성 패키지를 설치해야 합니다. 제공업체 목록에서 알 수 있듯이, 지원 기능은 선택한 모델과 API에 따라 다릅니다.

이 목록에는 OpenAI, Anthropic, Google/Gemini, AWS Bedrock, Groq, Mistral, xAI, Ollama가 포함되어 있습니다. 그 밖에 문서에 나온 연결 경로는 다음과 같습니다.

• 모델 및 추론 서비스: Alibaba Cloud/Qwen, Cerebras, Cohere, Crusoe, DeepSeek, Fireworks AI, Heroku AI, Hugging Face, Meta, Moonshot AI/Kimi, Nebius AI Studio, OVHcloud AI Endpoints, SambaNova, Snowflake Cortex, Together AI, Z.AI.
• 클라우드, 게이트웨이, 자체 호스팅 옵션: Google Cloud/Vertex AI, Microsoft Azure/Foundry, Pydantic AI Gateway, LiteLLM, OpenRouter, Vercel AI Gateway, vLLM.
• 그 밖의 접근 방식 및 의사결정 모델 연결 경로: GitHub Copilot, OpenAI Codex, OpenAI Decisions API, System One API, TypeSafe (Jev).

이 이름들은 모델에 접근하는 여러 방식을 가리킵니다. 모두 같은 기능을 제공해 서로 그대로 대체할 수 있다는 뜻은 아닙니다. 로컬 모델은 호스팅된 최첨단 모델과 툴 동작이 다를 수 있고, 호환 API라도 스키마 제약은 다를 수 있습니다.

창업자에게 모델 이식성은 다른 선택지로 옮길 여지와 실험할 기회를 줍니다. 이를 구현하는 개발자에게는 수용 기준이 그대로 남습니다. 교체할 모델이 같은 사례에서 올바른 툴을 선택하고, 출력 스키마를 지키며, 받아들일 만한 판단을 내리는지 확인해야 합니다. 운영 환경의 기본 모델을 바꾸기 전에 그 근거를 확보해야 합니다.

MCP와 내구성 있는 실행: 툴 연결과 실행 복구

MCP는 에이전트를 툴 서버에 연결하고, 내구성 있는 실행은 중단 이후에도 작업을 이어 갈 수 있도록 돕습니다. 두 기능이 해결하는 문제는 서로 다릅니다.

Model Context Protocol, 즉 MCP는 애플리케이션이 AI 클라이언트에 툴과 맥락을 제공하는 방식을 표준화합니다. Pydantic AI의 MCP 기능은 서버 URL, 클라이언트 또는 툴셋 입력을 받으며, 지원되는 경우 제공업체 자체 MCP 옵션도 사용할 수 있습니다. 덕분에 에이전트마다 연동 코드를 새로 작성하지 않고 툴 서버를 재사용할 수 있습니다. 다만 어떤 고객에게 그 서버의 작업을 허용할지까지 결정해 주지는 않습니다.

내구성 있는 실행은 진행 상태를 보존해 장애, 재시작, 긴 대기 이후에도 작업을 계속할 수 있게 하는 방식입니다. 현재 내구성 문서에는 9가지 솔루션이 나와 있습니다.

• 공급사 팀과 공동으로 유지보수: Temporal, DBOS, Prefect, Restate, AWS Lambda.
• 외부 SDK 통합: Kitaru, Apache Airflow, Absurd, pgtask.

다른 엔진을 위한 백엔드 빌더도 있습니다. 에이전트가 자신을 시작한 요청이나 프로세스가 끝난 뒤에도 실행되어야 한다면 문서에 나온 통합 중 하나를 선택하는 것이 좋습니다. 이런 통합이 제공된다고 해서 Agent를 호출하는 것만으로 중단에 대비한 배포 환경이 갖춰지는 것은 아닙니다.

환불 권고안을 작성하고, 승인을 기다린 뒤, 실제 환불을 처리하는 고객 지원 작업을 생각해 볼 수 있습니다. 실행 상태를 저장하면 승인 대기 중인 작업을 보존할 수 있지만, 결제 작업에는 여전히 멱등성이 필요합니다. 같은 요청을 반복해도 환불이 추가로 발생해서는 안 됩니다. 이미 수행한 작업을 어떻게 식별할지, 처리 여부가 불분명할 때 어떻게 실제 상태를 확인하고 정합성을 맞출지 정해야 합니다. 이는 엔진과 별개로 애플리케이션이 맡아야 할 책임입니다.

Pydantic AI 평가: 객체에 담긴 판단까지 검증하기

Pydantic Evals는 출력을 파싱할 수 있는지에 그치지 않고, 에이전트가 받아들일 만한 수준으로 작업을 수행했는지 평가합니다. 코드 중심의 별도 평가 패키지이므로 Pydantic AI 없이도 사용할 수 있습니다. 사례와 평가기를 정의하고, 각 사례에 대해 작업을 실행한 뒤, 보고서를 확인하는 방식입니다. 문서는 최종 출력뿐 아니라 실행 중 어떤 행동을 어떤 순서로 했는지를 보여 주는 툴 호출 경로를 평가하는 방법도 다룹니다.

앞의 문의 분류 예제라면 중복 청구, 로그인 실패, 계정 맥락 누락, 기존 지침을 무시하라고 요구하는 메시지로 평가 사례를 구성합니다. 문의 유형, 담당자에게 넘길지에 대한 판단, 필요한 계정 조회가 실제로 이루어졌는지를 확인합니다. 추가 질문을 하는 것이 적절한 답인 사례도 포함해야 합니다.

운영자에게 트레이스는 개별 실행을 설명하고, 평가는 여러 사례에 걸친 동작을 측정합니다. Pydantic AI는 애플리케이션 텔레메트리 표준인 OpenTelemetry를 사용하며, 계측 기능을 통해 다른 관측 백엔드도 지원합니다. 어떤 사례에서 실패하면 모델 요청과 툴 호출을 살펴보고, 그 사례를 평가 데이터셋에 남기는 것이 좋습니다.

선택적으로 사용할 수 있는 Pydantic Logfire는 에이전트·모델·툴 트레이싱을 제공합니다. 가격 페이지에 따르면 Personal 요금제는 무료이며, Team은 월 $49부터 시작하고 추가 사용량과 좌석은 별도로 과금합니다.

다른 AI 에이전트 프레임워크보다 Pydantic AI를 선택할 때

만들려는 기능에서 가장 어려운 부분에 맞춰 추상화 수준을 선택해야 합니다. 기존 도메인 모델과 서비스를 활용하는 Python 개발자라면, 타입이 지정된 입력·툴·출력의 통합이 핵심 과제일 때 Pydantic AI를 후보에 올릴 만합니다. 기술 창업자라면 사업에서 설명하고 유지보수할 수 있는 가장 작은 운영 시스템을 남기는 선택이 무엇인지 따져봐야 합니다.

Pydantic AI와 LangGraph 비교

에이전트를 둘러싼 워크플로를 명시적으로 설계하려면 LangGraph가 더 적합한 출발점입니다. 공식 문서는 장시간 실행되는 상태 유지형 에이전트, 내구성 있는 실행, 사람의 개입을 중심으로 설명합니다. 근거 수집, 승인 획득, 허가된 작업 실행, 결과 대조처럼 반드시 거쳐야 할 단계가 있는 애플리케이션을 떠올리면 됩니다.

Pydantic AI는 애플리케이션이 이미 제어하는 프로세스 안에 타입이 지정된 에이전트를 구성 요소로 넣을 때 매력적입니다. 내구성 있는 워크플로에도 참여할 수 있으므로 상태를 영속적으로 저장해야 한다는 이유만으로 선택이 정해지지는 않습니다. 핵심은 에이전트 주변의 업무 프로세스를 모델링하려는지, 주로 에이전트 자체의 동작을 설정하려는지에 있습니다. LangGraph에서는 워크플로 설계와 상태 관리를 직접 책임져야 합니다. Pydantic AI에서는 편리한 에이전트 인터페이스가 전체 프로세스까지 설계해 주지는 않는다는 한계를 감안해야 합니다.

Pydantic AI와 LangChain 비교

LangChain의 기존 모델·툴 통합과 에이전트 구조가 애플리케이션에 잘 맞는다면 합리적인 선택입니다. LangChain 개요에 따르면 LangChain 에이전트는 LangGraph를 기반으로 만들어집니다. 따라서 상위 수준의 에이전트 API를 선택해도 그 아래의 런타임 기반은 유지됩니다.

의존성과 출력 규약이 기존 코드 작성 방식에 잘 맞는 Python 서비스라면 Pydantic AI를 선택할 만합니다. 이미 잘 동작하는 LangChain 기능은 마이그레이션으로 어떤 복잡성을 없앨 수 있는지 구체적으로 설명할 수 있을 때까지 유지하는 편이 좋습니다. 동작이 에이전트 계층과 워크플로 계층을 넘나든다면 LangChain의 추상화 구조를 이해해야 합니다. 라이브러리를 바꾸는 것만으로는 그 일이 사라지지 않고 옮겨 갈 뿐입니다. 두 도구의 관계는 LangChain과 LangGraph 비교에서 더 자세히 다룹니다.

OpenAI Agents SDK와 직접 API 호출은 언제 선택하나요?

OpenAI Agents SDK는 애플리케이션이 에이전트 루프를 직접 관리하면서 툴, 에이전트 간 작업 이관, 트레이싱을 활용하려는 경우에 적합합니다. SDK는 애플리케이션 안에서 실행되며 구조화된 출력을 지원합니다. 제공업체 인터페이스를 통해 OpenAI 외의 모델도 사용할 수 있습니다. 타입이 지정된 출력이나 제공업체 선택을 Pydantic AI만의 기능으로 보는 것은 정확하지 않습니다.

유지하려는 OpenAI 연동 구조에 이 SDK의 에이전트 및 작업 이관 방식이 잘 맞는다면 선택할 만합니다. Python 의존성 모델과 제공업체 설정 방식이 더 잘 맞는다면 Pydantic AI를 선택하면 됩니다. 어느 쪽을 쓰든 배포, 툴 접근 권한, 애플리케이션의 올바른 동작은 직접 책임져야 합니다.

모델 요청 하나에 소량의 결정론적 코드를 덧붙이는 작업이라면 API를 직접 호출하는 것이 좋습니다. 직접 API를 호출해도 이미 스키마로 제한된 출력을 받을 수 있습니다. 영수증 정보 추출 결과를 Pydantic 객체로 만든다는 이유만으로 에이전트 프레임워크가 필요한 것은 아닙니다. 여러 기능에서 툴 호출 루프, 검증 재시도, 계측을 반복해서 구현하게 되는 시점이 이 접근 방식의 한계입니다.

더 넓은 선택지를 살펴보려면 기존 AI 에이전트 프레임워크 가이드를 참고할 수 있습니다. 워크플로를 명시적으로 제어할지, 전문 역할을 맡은 에이전트들을 구성할지가 남은 고민이라면 LangGraph와 CrewAI 비교를 이어서 읽으면 됩니다.

타입이 지정된 에이전트에 대한 과도한 기대

타입을 지정한 에이전트가 곧바로 올바르게 동작하는 운영 시스템이 된다는 주장은 과장입니다. 라이브러리만으로 없앨 수 없는 경계가 있습니다.

• 타입 안전성이 사실의 정확성을 보장하지는 않습니다. 형식이 올바른 답도 사용자의 요청을 잘못 이해할 수 있습니다. 어떤 내용을 신뢰할 수 있는 원본 기록과 대조할지 정해야 합니다.
• 모델 이식성이 같은 품질을 뜻하지는 않습니다. 제공업체 설정을 바꿀 때도 프롬프트를 바꿀 때와 동일하게 작업을 평가해야 합니다.
• 내구성 기능이 배포를 자동으로 해결하지는 않습니다. 기능에 필요한 엔진, 저장소, 복구 경로를 선택하고 운영해야 합니다.
• 재시도도 추가 작업입니다. 모델을 다시 요청하면 지연 시간과 사용량이 늘어납니다. 재시도 한도를 소진했을 때 애플리케이션이 어떻게 처리할지 명확히 정해야 합니다.

다음 Python 기능에 이미 툴과 구조화된 판단 결과가 필요하다면 지금 도입을 검토할 만합니다. 기존 시스템이 잘 동작하고 기대하는 이점이 데모 코드가 더 깔끔해 보이는 정도라면 프레임워크 마이그레이션을 서두를 이유가 없습니다. 충분한 검증과 오류 처리를 갖춘 단순 추출 호출이라면 큰 영향을 받지 않습니다.

Pydantic AI 자주 묻는 질문

다음 주에 출시할 기능, 어디서 시작할까요?

작은 읽기 전용 기능의 합격 기준을 명확히 정한 뒤 자율성을 넓혀 가는 것이 좋습니다. 고객 지원 제품이라면 예제의 문의 분류 객체로 시작하고, 최종 계정 조치는 일반 애플리케이션 코드에서 처리합니다.

AI 기능 개발에 관한 실용적인 소식을 받아보려면 뉴스레터를 구독할 수 있습니다.