# Pydantic AI

> Build typed LLM applications with PydanticAI: schema-constrained outputs, tool integration, validation, retries, and deterministic downstream handoffs. Use when users need reliable structured outputs instead of free-form text generation.

- Skill: `akillness/pydantic-ai` (Agent Skill)
- Install (CLI): `npx skillmds add akillness/pydantic-ai`
- Raw SKILL.md: https://api.skillmd.com/api/skills/akillness/pydantic-ai/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: akillness (https://skillmd.com/u/akillness)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/akillness/pydantic-ai

---


# PydanticAI

## When to use this skill
- LLM 출력이 JSON/객체 스키마를 반드시 따라야 할 때
- 후속 자동화(저장/분석/API 호출)에 안정적으로 넘겨야 할 때
- 자유서술보다 검증 가능한 구조화 출력이 중요한 경우

## Instructions

### Step 1) 스키마 우선 설계
- 먼저 Pydantic 모델을 정의하고 필수/선택 필드 분리
- enum/range/regex 제약을 명시
- 오류 메시지는 사용자 교정 가능 형태로 설계

### Step 2) Agent + Tool 결합
- 도구 입출력도 Pydantic 타입으로 통일
- 실패 시 재시도 규칙(필드 누락/타입 불일치)을 분리
- 모델 출력이 스키마 미준수면 즉시 재질문(repair prompt)

### Step 3) 검증/복구 루프
- ValidationError를 카테고리화(누락/형식/논리)
- 동일 오류 반복 시 프롬프트가 아니라 스키마 복잡도 재검토
- 최종 결과에 신뢰 플래그(validated, repaired, failed) 포함

### Step 4) 운영 적용
- DB 저장 전 2차 검증(서버 측) 수행
- 버전드 스키마(`v1`,`v2`)로 호환성 관리
- 관찰 지표: first-pass success, retry rate, field error rate

## Examples
- 요청: "리서치 결과를 항상 동일 포맷 JSON으로 받아서 파이프라인에 넣고 싶다"
- 적용: `ResearchSummary` 스키마 정의 후 Agent 결과를 강제 검증
- 결과: 파싱 실패율 감소, 후속 자동화 안정화

## Best practices
1. 자연어 요구사항을 먼저 스키마로 번역한다.
2. 스키마는 작게 시작하고 점진적으로 확장한다.
3. 재시도 횟수보다 오류 분류 품질을 먼저 개선한다.

## References
- https://github.com/pydantic/pydantic-ai