🐍02. Agent 타입안전: deps와 output 설계

Agent를 오래 운영하려면 “대충 텍스트 받기”에서 벗어나야 합니다. PydanticAI에서 그 출발점이 deps_type과 output_type입니다. 이 둘을 먼저 잡으면, 나중에 기능을 늘려도 코드가 덜 흔들립니다.

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

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

• 흐름: dependencies 선언/주입 → 동기·비동기 의존성 분리 → output 모드 선택(구조화/함수형) → 출력 검증기(output validator)로 품질 고정.
• 이번 편에서 빠지면 안 되는 포인트:
  • deps는 단순 설정값이 아니라 실행 문맥 주입 레이어로 설명한다.
  • output_type + 검증 실패 시 재시도/보정 흐름을 함께 다룬다.
  • dependency override(테스트/환경 전환)를 개요에 명시한다.
• 공식 문서 체크 링크:
  • https://ai.pydantic.dev/dependencies/index.md
  • https://ai.pydantic.dev/output/index.md
  • https://ai.pydantic.dev/agent/index.md

왜 deps/output부터 잡아야 하나

deps_type은 런타임에 Agent가 사용할 의존성(예: user_id, DB connection)을 타입으로 고정합니다. output_type은 모델이 마지막에 반환해야 하는 구조를 고정합니다.

공식 문서:

• Dependencies: https://ai.pydantic.dev/dependencies/
• Output: https://ai.pydantic.dev/output/

flowchart TD
  A[RunContext로 deps 전달] --> B[Tool/Instructions에서 사용]
  B --> C[모델 응답 생성]
  C --> D[output_type 검증]
  D --> E[통과 시 최종 반환]
  D --> F[실패 시 재시도/수정 유도]

최소 실전 예시

from dataclasses import dataclass
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext
 
@dataclass
class Deps:
    customer_id: int
 
class Out(BaseModel):
    answer: str = Field(description='고객 안내 문구')
    risk: int = Field(ge=0, le=10)
 
agent = Agent('openai:gpt-5.2', deps_type=Deps, output_type=Out)

핵심은 “리뷰가 쉬운 결과”를 강제하는 것입니다.

미니 사례 A: 운영자가 리스크 레벨을 못 믿었던 문제

예전에는 모델이 상황에 따라 “위험/낮음”처럼 제각각 표현해서 자동화 파이프라인에서 분기 처리가 어려웠습니다. risk: int(0~10)로 고정하니 룰 엔진 연결이 쉬워졌습니다.

미니 사례 B: 고객 정보 주입이 불안정했던 문제

프롬프트에 고객 정보를 문자열로 붙이던 방식은 누락이 잦았습니다. deps_type으로 강제해 RunContext에서 꺼내 쓰게 바꾸니 누락 케이스가 줄었습니다.

지금 바로 적용 순서

1. 기존 Agent 출력에서 반드시 필요한 필드 2~3개를 먼저 확정
2. output_type 모델 정의
3. 외부 상태값(user/team/db)을 deps_type으로 이동
4. 같은 입력 3회 테스트 후 필드 일관성 확인

성공 판정:

• 결과 JSON/객체 필드가 고정됐다
• 사람이 아닌 코드가 결과를 안정적으로 읽을 수 있다
• deps 누락 시 즉시 문제를 발견할 수 있다

다음 글

• 🐍03. Function Tools와 Built-in Tools
• 🐍01. 설치·헬로월드: 첫 Agent 실행
• 🐍 PydanticAI 허브