문서버전 1.0 · 업데이트
Pydantic AI는 Pydantic을 만든 팀의 에이전트 프레임워크로, 타입이 있고 검증된 결과를 중심으로 설계됐습니다.
Agent에 모델과 (선택적으로) output_type을 주면 신뢰할 수 있는 파이썬 객체를 돌려줍니다 — OpenAI·Anthropic·Gemini 등 어디서든.
flowchart LR prompt[prompt] --> agent[Agent] agent --> model[model] model --> out[typed result]
코드 샘플 탭에는 일반 에이전트와 구조화 출력 에이전트 예시가 있습니다 — 선택기에서 골라 비교해 보세요.
무거운 프레임워크보다 파이썬 코드베이스에 잘 맞는 에이전트 — 타입 결과·의존성 주입·검증 — 가 필요할 때 Pydantic AI를 쓰세요.
오픈소스(MIT)라 무료로 셀프호스트하며, LLM 호출 비용만 부담합니다.
출처 ↗ · 기준일 2026-06-27
평범한 파이썬을 쓰는 느낌의 작고 타입이 있는 에이전트가 필요할 때 쓰세요.
run_sync가 모델을 호출해 결과를 돌려주고, 응답은 result.output에 있습니다.
flowchart LR prompt[prompt] --> agent[Agent] agent --> model[model] model --> out[result]
from pydantic_ai import Agent
# Model id is "provider:model" — swap providers by changing the string.
agent = Agent("anthropic:claude-opus-4-8", system_prompt="Be concise.")
result = agent.run_sync("Summarize Pydantic AI in one sentence.")
print(result.output)
에이전트 결과가 자유 텍스트가 아니라 검증된 객체여야 할 때 output_type을
넘기세요.
Pydantic AI가 모델 출력을 모델에 맞춰 제약·검증하고 타입이 있는 인스턴스를 돌려줍니다.
flowchart LR prompt[prompt] --> agent[Agent] agent --> obj[typed object]
from pydantic import BaseModel
from pydantic_ai import Agent
class Place(BaseModel):
city: str
country: str
agent = Agent("openai:gpt-4o", output_type=Place)
result = agent.run_sync("Where is the Eiffel Tower?")
print(result.output) # Place(city='Paris', country='France')
실제로 실행 가능한 미니 프로젝트입니다. 받아서 Docker로 실행해 보세요.
2026년 6월 28일
Pydantic AI — 타입이 있는 에이전트아주 작은 Pydantic AI 스크립트입니다. 자유 텍스트에서
Person(name·age·occupation)을 추출합니다. 에이전트의 output_type이 Pydantic
모델이라, 파싱할 문자열이 아니라 검증된 객체를 돌려받습니다.
cd samples/pydantic-ai_1
cp .env.sample .env
# .env 편집: MODEL과 해당 제공자의 키를 설정
MODEL은 provider:model 형식입니다:
| 제공자 | MODEL |
.env의 키 |
|---|---|---|
| Anthropic Claude | anthropic:claude-opus-4-8 |
ANTHROPIC_API_KEY |
| OpenAI | openai:gpt-4o |
OPENAI_API_KEY |
| Google AI Studio | google-gla:gemini-2.5-flash |
GEMINI_API_KEY |
.env는 gitignore 처리되어 있고, .env.sample만 커밋됩니다.
cd samples/pydantic-ai_1
docker build -t aas-pydantic-ai .
docker run --rm --env-file .env aas-pydantic-ai \
"Ada Lovelace, 36, was a mathematician and the first programmer."
호스트 Docker 데몬과 통신하는 dev container(Docker-outside-of-Docker)에서는 위의
포그라운드 docker run이 종종 아무것도 출력하지 않고 exit 0으로 끝납니다. 하지만
실행 자체는 성공한 것입니다. 스크립트는 끝까지 실행되고 출력도 Docker가 모두
캡처하는데, 실시간 attach 스트림만 그 출력을 VM 경계에서 흘려버립니다.
detached로 실행하고 로그를 따라가세요:
cd samples/pydantic-ai_1
docker build -t aas-pydantic-ai .
docker logs -f "$(docker run -d --env-file .env aas-pydantic-ai \
"Ada Lovelace, 36, was a mathematician and the first programmer.")"
cd samples/pydantic-ai_1
pip install -r requirements.txt
python app.py "Ada Lovelace, 36, was a mathematician and the first programmer."
python-dotenv가 .env를 자동으로 불러옵니다.
모델과 실행마다 결과가 달라집니다 — LLM은 비결정적입니다. 형태는 Pydantic 모델이 고정하고, 값은 추출됩니다. 아래는
anthropic:claude-opus-4-8로 실행한 한 예입니다.
name='Ada Lovelace' age=36 occupation='Mathematician'
파일
# Copy this file to `.env` and fill in the key for the provider you want.
# cp .env.sample .env
#
# Pydantic AI model id is "provider:model".
# Pick the model. Examples:
# anthropic:claude-opus-4-8 Anthropic Claude -> needs ANTHROPIC_API_KEY
# openai:gpt-4o OpenAI -> needs OPENAI_API_KEY
# google-gla:gemini-2.5-flash Google AI Studio -> needs GEMINI_API_KEY
MODEL=anthropic:claude-opus-4-8
# Set only the key for the provider you chose; leave the rest blank.
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GEMINI_API_KEY=
# Local secrets — never commit the real .env
.env
# ...but keep the committed template (root .gitignore's `.env.*` would hide it).
!.env.sample
"""Pydantic AI: a typed agent that returns a validated object.
Extracts a `Person` from free text. The agent's `output_type` is a Pydantic
model, so the result is a validated Python object — not text to parse. MODEL is
a "provider:model" string, so switch providers by changing it.
Run:
docker build -t aas-pydantic-ai .
docker run --rm --env-file .env aas-pydantic-ai "Ada Lovelace, 36, was a mathematician."
"""
import os
import sys
from dotenv import load_dotenv
from pydantic import BaseModel
from pydantic_ai import Agent
# Load .env when running locally; in Docker the keys come from --env-file.
load_dotenv()
MODEL = os.environ.get("MODEL", "anthropic:claude-opus-4-8")
class Person(BaseModel):
name: str
age: int
occupation: str
def main() -> None:
text = " ".join(sys.argv[1:]) or "Ada Lovelace, 36, was a mathematician and the first programmer."
agent = Agent(MODEL, output_type=Person)
result = agent.run_sync(f"Extract the person from: {text}")
print(result.output)
if __name__ == "__main__":
main()
# Minimal image for the Pydantic AI sample.
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
# Provide your config at run time (.env is NOT baked into the image):
# docker run --rm --env-file .env aas-pydantic-ai "<text to extract from>"
ENTRYPOINT ["python", "app.py"]
pydantic-ai>=2.0,<3
python-dotenv>=1.2,<2