🐍00. 오리엔테이션: 왜 PydanticAI인가

PydanticAI는 “LLM 데모 코드”를 “운영 가능한 에이전트 코드”로 바꿀 때 특히 강한 선택지입니다. 핵심은 단순합니다. 타입으로 입력·도구·출력을 계약처럼 고정해서, 실행할수록 품질이 흔들리는 문제를 줄이는 데 유리합니다.

처음에는 Agent 하나로 시작할 수 있고, 이후 Tool·MCP·Graph·Evals·Durable Execution으로 점진 확장할 수 있습니다. 즉, 작게 시작해서 크게 운영하기 좋은 구조입니다.

AI 활용 안내: 이 문서는 생성형 AI를 활용해 작성했으며, Pydantic AI 공식 문서를 1차 출처로 검토해 정리했습니다.

공식문서 흐름 점검 (개요 보완)

• 흐름: index 포지셔닝 → install 설치 분기(일반/slim) → agent 실행 방식(run_sync/run, Run vs Conversation) → models/overview 공급자·폴백·동시성 → logfire 관측.
• 이번 편에서 빠지면 안 되는 포인트:
  • Runs vs. Conversations를 분리해서 설명한다.
  • 모델 연결은 “모델명”이 아니라 Provider + 모델 + 예외/폴백 관점으로 설명한다.
  • 관측(Tracing)과 디버깅을 입문 단계에서 함께 소개한다.
• 공식 문서 체크 링크:
  • https://ai.pydantic.dev/index.md
  • https://ai.pydantic.dev/agent/index.md
  • https://ai.pydantic.dev/models/overview/index.md

핵심 요약

• PydanticAI의 중심은 Agent이며, 이 Agent는 instructions / tools / output_type / deps_type / model을 하나의 실행 단위로 묶습니다.
  공식 문서: https://ai.pydantic.dev/agent/
• 설치는 빠르게 시작 가능하고(pip install pydantic-ai), 필요 시 pydantic-ai-slim[...]으로 의존성을 줄일 수 있습니다.
  공식 문서: https://ai.pydantic.dev/install/
• 모델은 특정 벤더에 묶이지 않는 구조라서 OpenAI, Anthropic, Gemini 등으로 라우팅을 바꾸기 쉽습니다.
  공식 문서: https://ai.pydantic.dev/models/overview/
• 이 시리즈의 목표는 “코드가 돌아간다”에서 끝나지 않고 “테스트/관측/복구가 된다”까지 가져가는 것입니다.

왜 지금 PydanticAI인가

에이전트 프로젝트가 초반에 망가지는 이유는 모델 성능 자체보다, 운영 계약이 느슨하기 때문인 경우가 많습니다. 프롬프트는 길어지는데 출력 형식은 매번 달라지고, 도구 인자 검증이 약해서 재시도가 폭발하는 패턴이 자주 나옵니다.

PydanticAI는 이 구간을 “타입 기반 계약”으로 당겨옵니다. deps_type으로 런타임 의존성(예: DB 연결, 사용자 ID)을 명시하고, output_type으로 최종 결과 구조를 고정하며, Tool 입력도 스키마로 검증합니다.

공식 문서에서 Agent를 “instructions, tools, structured output, dependencies, model의 컨테이너”로 설명하는 이유가 바로 여기입니다.
공식 문서: https://ai.pydantic.dev/agent/

flowchart TD
  A[요청 입력] --> B[Agent 계약: instructions + deps + tools]
  B --> C[모델 호출]
  C --> D[도구 호출/재시도]
  D --> E[output_type 검증]
  E --> F[안정된 결과 반환]

현장 미니 사례 2개

사례 1) 고객지원 봇: 답변은 그럴듯한데 조치가 들쭉날쭉한 문제

초기에는 “친절하게 답변해” 수준의 프롬프트만 사용해, 같은 질문에서도 카드 정지 여부 같은 핵심 조치가 매번 달라졌습니다.

개선은 세 단계였습니다.

1. 출력을 support_advice / block_card / risk 같은 구조로 고정 (output_type)
2. 고객 ID와 DB 연결을 deps_type으로 분리
3. 잔액 조회/위험 판정 로직을 Tool로 분리

이후에는 리뷰 포인트가 “문장 톤”이 아니라 “risk 기준이 맞는가”로 이동했고, QA 시간이 줄었습니다.

참고 예제(공식): https://ai.pydantic.dev/examples/bank-support/

사례 2) 사내 리서치 에이전트: 모델 교체 때마다 코드가 깨지는 문제

한 모델에 하드코딩된 SDK 호출이 많아서, 공급자 변경 시 코드 수정 범위가 커졌습니다.

PydanticAI로 전환 후에는 <provider>:<model> 형태로 모델 라우팅을 바꾸고, 필요할 때만 Provider/Model 클래스를 직접 지정하는 방식으로 정리했습니다. 결과적으로 모델 교체 실험 주기가 짧아졌고, 장애 시 대체 경로 설계가 쉬워졌습니다.

공식 문서: https://ai.pydantic.dev/models/overview/

용어를 쉬운 비유로 정리

• Agent: 매장 점장(전체 운영 규칙 담당)
• Tool: 점장이 호출하는 직원(검색, DB 조회, 계산)
• deps_type: 오늘 근무표(누가 어떤 권한/데이터를 들고 들어오는지)
• output_type: 고객에게 건네는 영수증 양식(형식이 매번 바뀌면 안 됨)

이 비유를 기억하면, “프롬프트를 더 길게 쓸까?”보다 “계약이 비어 있는 곳이 어디지?”를 먼저 보게 됩니다.

10분 실습 (누가/무엇을/순서)

개발자 1명이 로컬에서 바로 해볼 수 있는 입문 루틴입니다.

1. 설치
   • pip install pydantic-ai 또는 uv add pydantic-ai
   • 공식 문서: https://ai.pydantic.dev/install/
2. 첫 Agent 실행
   • Agent(...) 생성 후 run_sync()로 단일 질의 실행
3. 출력 계약 추가
   • 간단한 Pydantic 모델을 output_type으로 지정
4. 검증
   • 같은 입력 3회 반복 실행해 결과 구조가 유지되는지 확인

성공 판정:

• 실행은 1회가 아니라 3회 반복해도 결과 구조가 유지된다
• 자유 텍스트가 아니라 합의한 필드 구조로 결과가 나온다
• 다음 편(01편)에서 그대로 확장 가능한 최소 코드가 남는다

칠판 치트시트

1. PydanticAI는 “프롬프트 프레임워크”보다 “운영 계약 프레임워크”에 가깝다
2. Agent = instructions + tools + deps + output + model
3. 처음부터 output_type을 잡아야 재작업이 줄어든다
4. 모델 교체 가능성을 열어두면 실험 속도가 빨라진다
5. 목표는 데모 성공이 아니라 반복 운영 성공이다

다음 글

• 🐍01. 설치·헬로월드: 첫 Agent 실행
• 🐍 PydanticAI 시리즈 허브
• 🧠 Context Engineering 01. 프롬프트 한계