🐍04. 메시지 히스토리·Retry·에러 복원

에이전트 품질은 단발 응답보다 반복 대화와 실패 상황에서 갈립니다. 히스토리를 어떻게 넘기고, 어떤 재시도 정책을 쓰느냐가 운영 안정성을 결정합니다.

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

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

• 흐름: 메시지 저장/복원(JSON) → 히스토리 프로세서 전처리 → HTTP 재시도 전략(wait/transport) → RateLimit/네트워크 장애 복구 패턴.
• 이번 편에서 빠지면 안 되는 포인트:
  • 메시지 히스토리와 재시도를 서로 다른 실패 계층으로 구분한다.
  • retry-after 대응, 네트워크 오류 재시도 정책을 개요에 포함한다.
  • 히스토리 프로세서 테스트 방법을 한 줄이라도 명시한다.
• 공식 문서 체크 링크:
  • https://ai.pydantic.dev/message-history/index.md
  • https://ai.pydantic.dev/retries/index.md
  • https://ai.pydantic.dev/agent/index.md

히스토리와 재시도의 역할 분리

• 메시지 히스토리: 맥락 유지
• 재시도 정책: 일시 오류/검증 실패 복구

공식 문서:

• Message history: https://ai.pydantic.dev/message-history/
• HTTP retries: https://ai.pydantic.dev/retries/

flowchart TD
  A[질문 입력] --> B[기존 히스토리 결합]
  B --> C[모델/도구 실행]
  C --> D{성공?}
  D -->|예| E[결과 저장]
  D -->|아니오| F[재시도 정책 적용]
  F --> C

미니 사례 A: 장문 대화에서 앞선 합의를 자꾸 잊던 문제

히스토리를 통째로 계속 붙이던 팀은 후반부에서 지시 충돌이 생겼습니다. 핵심 합의만 요약해 주기적으로 정리해 넘기자 품질이 안정됐습니다.

미니 사례 B: 외부 API 순간 장애로 전체 작업이 실패한 문제

재시도 없이 단발 호출하던 구조는 장애 순간마다 업무가 끊겼습니다. 재시도 횟수와 백오프를 설정해 일시 오류를 흡수하니 성공률이 개선됐습니다.

적용 체크리스트

1. 히스토리 전달 정책 문서화(전체/요약/최근 N턴)
2. 재시도 대상 분리(네트워크 오류 vs 비즈니스 오류)
3. 실패 로그에 재현 가능한 입력/상태 남기기

성공 판정:

• 같은 대화를 길게 이어도 맥락 손실이 줄었다
• 일시 장애 시 자동 복구 비율이 올라갔다
• 장애 원인을 로그에서 재현할 수 있다

다음 글

• 🐍05. 스트리밍·구조화 출력·멀티모달 입력
• 🐍03. Function Tools와 Built-in Tools
• 🐍 PydanticAI 허브