만약 여러분이 LLM 기능을 배포하고 그것이 프로덕션에서 잘못된 형식의 JSON을 반환하는 것을 본 적이 있다면, PydanticAI는 여러분을 위해 만들어졌습니다. 이것은 Pydantic 팀이 개발한 Python 에이전트 프레임워크이며, 에이전트 개발의 중심에 타입 안전하고 유효성이 검증된 출력을 둡니다. 이 가이드는 PydanticAI가 무엇인지, 왜 타입 안전성이 에이전트에게 중요한지, 실제로 사용하게 될 핵심 개념들, 그리고 LangGraph와 같은 다른 Python 프레임워크와 어떻게 비교되는지 설명합니다.
PydanticAI란 무엇인가
PydanticAI는 Python용 오픈 소스, 공급업체 독립적인 에이전트 프레임워크입니다. Pydantic Validation 및 Pydantic Logfire를 개발하는 동일한 팀에서 유지 관리하므로, 강력한 유효성 검사 기반과 명확한 설계 목표를 계승합니다: 에이전트를 구축하는 데 "그 FastAPI 느낌"을 선사하는 것입니다.
간단히 말해, 에이전트가 무엇을 해야 하는지, 어떤 도구를 호출할 수 있는지, 그리고 출력의 형태가 어떠해야 하는지 설명합니다. PydanticAI는 모델 호출을 처리하고, 모든 것을 Pydantic 모델과 대조하여 유효성을 검사하며, 모델이 맞지 않는 것을 반환하면 재시도합니다.
이 프로젝트는 여러 베타 버전을 거쳐 2026년 6월 23일에 안정적인 v2.0.0 릴리스에 도달했습니다. v2는 에이전트의 도구, 훅, 지침 및 모델 설정이 재사용 가능한 단위로 구성되는 하네스 우선(harness-first) 설계를 지향합니다. pip install pydantic-ai 또는 uv add pydantic-ai로 설치할 수 있습니다.
왜 타입 안전성이 에이전트에게 중요한가
LLM은 비결정적입니다. 같은 질문을 두 번 하면 두 가지 다른 형태의 답변을 받을 수 있습니다. 이는 채팅 상자에는 괜찮지만, 모델 출력을 실제 코드(데이터베이스 쓰기, API 호출, 청구 계산)에 연결하는 순간 문제가 발생합니다.
대부분의 에이전트 버그는 이러한 간극에서 발생합니다. 모델은 "대부분" 유효한 JSON을 반환하고, 파서는 테스트에서 작동하지만, 프로덕션 응답이 필드를 누락시키거나 답변을 산문으로 감싸면 파이프라인이 중단됩니다. 결국 방어적인 파싱, 정규식 정리, 재시도 루프를 수동으로 작성하게 됩니다.
PydanticAI는 출력 계약을 프레임워크의 일부로 만듦으로써 이러한 간극을 해소합니다. Pydantic 모델을 정의하고 이를 출력 유형으로 전달하면, 프레임워크는 반환되는 값이 해당 모델과 일치함을 보장합니다. 모델이 유효하지 않은 것을 반환하면, PydanticAI는 유효성 검사 오류를 LLM으로 다시 보내 재시도하도록 요청합니다. 여러분의 하위 코드(downstream code)는 희망적인 문자열이 아닌, 타입이 지정된 객체를 받게 됩니다.
이러한 아이디어는 도구 인수로도 확장됩니다. 모델이 여러분의 도구 중 하나를 호출할 때, PydanticAI는 함수가 실행되기 전에 여러분의 함수의 타입 힌트에 대해 인수를 유효성 검사합니다. 잘못된 인수는 절대 여러분의 비즈니스 로직에 도달하지 않습니다.
핵심 개념
PydanticAI는 표면 영역을 작게 유지합니다. 다섯 가지 아이디어가 여러분이 구축할 대부분을 다룹니다.
에이전트
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)
공급업체를 전환하기 위해 변경하는 것은 해당 모델 문자열뿐이며, 이는 여러분의 코드를 이식성 있게 유지합니다.
타입이 지정된 출력
Pydantic 모델을 output_type으로 전달하면 에이전트의 결과가 해당 모델에 대해 유효성 검사됩니다. 여러분은 타입이 지정된 객체를 돌려받으며, IDE는 모든 필드를 알게 됩니다. 다음은 구조화된 출력의 개요입니다:
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.')
print(result.output.priority) # an int, validated, not a guess
모델이 우선순위를 텍스트로 반환하거나 요약을 생략하면 유효성 검사가 실패하고 프레임워크가 재프롬프트합니다. 여러분은 원시 응답을 직접 파싱할 필요가 없습니다.
도구
도구는 모델이 외부로 확장될 수 있도록 합니다: 데이터베이스 쿼리, REST API 호출, 계산 실행. @agent.tool 데코레이터를 사용하여 도구를 등록합니다. PydanticAI는 함수의 타입 힌트와 독스트링을 읽어 모델이 보는 스키마를 구축한 다음, 모든 호출을 해당 스키마에 대해 유효성 검사합니다.
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."""
# ctx.deps holds your injected dependency
return await lookup_balance(ctx.deps, account_id)
모델은 언제 도구를 호출할지 결정합니다. 여러분의 함수는 이미 유효성 검사를 통과한 인수로만 실행됩니다.
종속성
실제 에이전트에는 컨텍스트가 필요합니다: 데이터베이스 연결, HTTP 클라이언트, 현재 사용자, API 키. PydanticAI는 종속성 주입(dependency injection)으로 이를 처리합니다. 에이전트에 deps_type을 선언한 다음, 도구 및 동적 지침 내에서 RunContext를 통해 이를 읽습니다. 전체 체인은 타입 안전성을 유지하며, 실제 종속성을 가짜(fake)로 교체할 수 있으므로 테스트가 더 쉬워집니다.
모델 독립적인 공급업체 및 스트리밍
PydanticAI는 OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity를 비롯하여 Azure AI Foundry 및 Amazon Bedrock과 같은 클라우드 옵션 및 자체 호스팅 모델 등 다양한 공급업체를 지원합니다. 공급업체 전환은 일반적으로 모델 문자열의 한 줄 변경으로 이루어집니다.
또한 데이터가 도착하는 대로 유효성 검사가 적용된 구조화된 출력을 스트리밍하여, 타입 보장을 포기하지 않고 부분 결과를 렌더링할 수 있습니다. 그리고 이 팀은 Pydantic Logfire도 개발하므로, 모든 실행에 대한 트레이싱, 디버깅, 비용 추적과 같은 관찰 가능성(observability)이 내장되어 있습니다.
PydanticAI가 다른 Python 에이전트 프레임워크와 비교되는 방식
단 하나의 "최고" 프레임워크는 없습니다. 각각 다른 것을 최적화합니다. PydanticAI가 어디에 적합한지 솔직하게 살펴보겠습니다.
| 프레임워크 | 핵심 강점 | 다음과 같은 경우에 가장 적합 |
|---|---|---|
| PydanticAI | 타입 안전하고 유효성이 검증된 출력 및 도구 인수 | 프로덕션 신뢰성과 깔끔한 타입 지정 데이터 흐름 |
| LangGraph | 명시적인 상태 저장 그래프 및 제어 흐름 | 장기 실행, 분기, 다단계 워크플로 |
| Google ADK | Google 생태계 내 다중 에이전트 오케스트레이션 | 깊이 있는 Gemini 및 Vertex AI 통합 |
| OpenAI Agents SDK | 핸드오프 기능이 있는 긴밀한 OpenAI 통합 | OpenAI 우선 스택 및 빠른 설정 |
PydanticAI의 강점은 유효성 검사 계층입니다. 에이전트가 타입이 지정된 데이터를 다른 시스템으로 공급하는 경우, 출력이 Pydantic 모델과 일치한다는 보장은 모든 유형의 런타임 오류를 제거합니다. LangGraph는 상태 머신과 복잡한 흐름에 대한 더 세밀한 제어를 제공합니다. OpenAI Agents SDK는 이미 OpenAI를 사용하고 있으며 에이전트 핸드오프 및 MCP 서버 지원과 같은 기능을 원하는 경우에 자연스러운 선택입니다.
이들을 혼합하여 사용할 수도 있습니다. PydanticAI는 더 큰 오케스트레이션 내에서 타입이 지정된 출력 계층으로 잘 작동합니다.
PydanticAI를 사용해야 하는 경우
다음과 같은 경우 PydanticAI를 사용하세요:
- 에이전트의 출력이 단순히 채팅창이 아니라 코드로 들어가고, 그 형태가 정확해야 할 때.
- 타입 체커와 IDE가 에이전트를 처음부터 끝까지 이해하기를 원할 때.
- 코드베이스에서 이미 Pydantic을 사용하고 있어서 모델 정의가 자연스럽게 느껴질 때.
- 공급업체 유연성이 필요하고 모델 전환을 위해 에이전트를 다시 작성하고 싶지 않을 때.
- 관찰 가능성(observability)이 중요하고 Logfire의 내장 트레이싱이 매력적일 때.
복잡한 분기가 있는 강력한 그래프 기반 오케스트레이션이 필요하고, 상태 머신 프레임워크가 더 직접적인 제어를 제공하는 경우에는 다른 대안을 찾아보세요.
에이전트 뒤의 API 테스트 및 모킹
PydanticAI 에이전트는 의존하는 API만큼만 신뢰할 수 있습니다. 모든 실행은 LLM 공급업체를 호출하며, 대부분의 유용한 에이전트 또한 여러분의 REST 엔드포인트나 서드파티 도구를 호출합니다. 이러한 호출에서 불안정한 동작, 예상치 못한 비용, 형태 불일치가 발생합니다. PydanticAI는 모델의 출력을 유효성 검사하지만, 여러분이 호출하는 업스트림 도구 API가 예상한 것을 반환하는지는 유효성 검사할 수 없습니다.
이것이 Apidog가 적합한 지점이며, 이는 프레임워크와는 다른 역할입니다. Apidog는 에이전트가 통신하는 기본 API를 테스트하고 모의(mock)하는 API 플랫폼입니다.
몇 가지 구체적인 사용 사례:
- LLM 또는 도구 엔드포인트를 모의(mock)합니다. 개발 중에는 확정적인 응답을 반환하는 모의 API로 도구를 지정합니다. 매 테스트 실행마다 토큰을 소모하는 것을 멈추고 반복 작업 중에 공급업체 속도 제한을 우회할 수 있습니다.
- 응답 형태를 단언(assert)합니다. REST 엔드포인트를
@agent.tool함수에 연결하기 전에, API 단언을 사용하여 실제 응답이 도구가 예상하는 구조와 일치하는지 확인하세요. 에이전트 실행 깊숙한 곳이 아니라 API 계층에서 누락된 필드를 잡아내세요. - 환경별 키를 관리합니다. 공급업체 키와 기본 URL을 별도의 Apidog 환경에 보관하여 로컬, 스테이징, CI 실행이 코드 변경 없이 올바른 대상에 도달하도록 합니다.
- LLM 엔드포인트를 직접 검증합니다. HTTP를 통해 공급업체를 호출하는 경우, Apidog로 ChatGPT API를 테스트하여 에이전트가 의존하기 전에 인증, 스트리밍 및 도구 호출 형식을 확인할 수 있습니다.
Apidog는 에이전트를 구축하거나 오케스트레이션하지 않으며, PydanticAI의 대안이 아닙니다. Apidog는 에이전트가 실행되는 API 표면을 테스트하고 모의(mock)하는 작업대입니다. 사용해보고 싶다면, Apidog를 다운로드하여 먼저 도구 엔드포인트 중 하나를 모의해보세요.
자주 묻는 질문
PydanticAI는 무료이며 오픈 소스인가요?
네. PydanticAI는 오픈 소스이며 pip install pydantic-ai 또는 uv add pydantic-ai를 사용하여 PyPI에서 설치할 수 있습니다. 프레임워크가 여러분을 대신하여 해당 API를 호출하므로, 사용하는 LLM 공급업체에 대한 비용은 여전히 지불해야 합니다. 개발 중 공급업체 비용을 절감하려면, 매 실행마다 실제 모델을 호출하는 대신 테스트 중에 API 응답을 모의(mock)할 수 있습니다.
PydanticAI는 어떤 모델과 작동하나요?
공급업체 독립적입니다. 문서에는 OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity뿐만 아니라 Azure AI Foundry 및 Amazon Bedrock과 같은 클라우드 옵션 및 자체 호스팅 모델이 나열되어 있습니다. Agent 생성자에 'anthropic:claude-sonnet-4-6' 또는 'openai:gpt-4o'와 같은 문자열을 전달하여 모델을 선택하며, 전환은 일반적으로 한 줄 변경으로 이루어집니다.
PydanticAI는 LangChain 또는 LangGraph와 어떻게 다른가요?
PydanticAI는 타입 안전성에 중점을 둡니다: Pydantic 모델로 뒷받침되는 유효성이 검증된 구조화된 출력 및 유효성이 검증된 도구 인수. LangGraph는 다단계, 분기 워크플로를 위한 명시적인 상태 저장 그래프에 중점을 둡니다. 보장된 출력 형태와 깔끔한 타입 지정 데이터 흐름이 우선순위라면 PydanticAI가 잘 맞습니다. 복잡한 상태 머신에 대한 세밀한 제어가 필요하다면, 그래프 프레임워크가 더 직접적인 제어 수단을 제공합니다.
사용하려면 Pydantic을 알아야 하나요?
도움이 되지만, 기본 사항은 빠르게 익힐 수 있습니다. BaseModel을 상속하는 클래스로 데이터 형태를 정의하며, PydanticAI는 이를 출력 및 도구 스키마에 사용합니다. API 테스트용 Python을 사용했거나 FastAPI를 다뤄본 적이 있다면, 이러한 사고방식은 친숙하게 느껴질 것입니다.
결론
PydanticAI는 에이전트 개발에 실용적인 것을 제공합니다: 모델의 출력과 도구 호출이 선언한 타입과 일치한다는 보장입니다. 이는 실제 프로덕션 버그의 원인을 제거하고 데이터 흐름을 깔끔하게 유지합니다. 복잡한 그래프 오케스트레이션보다 신뢰성과 타입이 지정된 출력이 더 중요할 때 PydanticAI를 선택하세요.
어떤 프레임워크를 선택하든, 에이전트 아래의 API는 여전히 테스트가 필요합니다. LLM 및 도구 엔드포인트를 모의(mock)하고, 응답 형태를 단언(assert)하며, Apidog에서 환경별 키를 관리하여 에이전트가 실제로 검증된 기반 위에서 실행되도록 하세요.