베타 7번을 거쳐 도착한 stable
Pydantic AI v2는 2026년 6월 23일 일곱 번의 베타를 지나 정식으로 굳었습니다. 같은 48시간 창 안에서 LlamaIndex Workflows 1.0도 안정화됐는데, 프레임워크 두 축이 나란히 stable을 찍었다는 사실보다 v2가 무엇을 바꿨는지가 마이그레이션을 좌우합니다. 이번 릴리스의 골자는 하네스 우선(harness-first) 재설계, 그리고 새 핵심 프리미티브인 역량(capability)입니다.
역량이라는 단일 프리미티브
역량은 툴·훅(hooks)·지침(instructions)·모델 설정을 하나의 합성 가능한 단위로 묶습니다. v1에서 에이전트 정의 여기저기에 흩어져 있던 이 네 가지가 v2에서는 역량이라는 한 개념으로 모든 계층에 도달합니다. Pydantic은 6월 한 달 동안 이 위에서 만든 헤드리스 코딩 에이전트를 자사 레포에 실제로 도그푸딩하며 개념을 프로덕션에서 검증했습니다.
그래서 이 글은 v2 출시를 뉴스로 소비하지 않습니다. v1식 평면 툴 목록을 역량 경계로 다시 그으려면 리팩터링 프로젝트의 규율이 필요하고, 그 규율의 핵심은 핀 고정과 회귀 골든셋과 이관 커버리지 측정입니다.
평면 툴 목록에서 역량 조립으로: v1→v2 이관 실행 가이드
(가) 기획·목표 수치. 마이그레이션은 코드를 열기 전에 완료의 정의부터 숫자로 못 박습니다. 역량 재사용률은 중복 툴 정의 수로 재는데, 같은 도구가 세 에이전트에 세 번 선언돼 있던 것을 역량 하나로 합치면 그 값이 3에서 1로 떨어집니다. 이관 커버리지는 v2로 넘어간 에이전트 경로 비율로 정의하고 1차 목표를 80% 이상, 역량별 회귀 통과율 98% 이상, 업그레이드 후 툴콜 스키마 검증 실패율 0.5% 이하를 출발 합격선으로 둡니다.
이 수치가 없으면 "v2로 대충 옮겼다"는 인상만 남고 무엇이 덜 옮겨졌는지 추적할 근거가 사라집니다. 반대로 커버리지 지표를 대시보드에 걸어 두면 남은 20%의 에이전트 경로가 눈에 보이고, 다음 스프린트의 작업 목록이 자동으로 산출됩니다.
(나) 실패 패턴과 복구. 첫째 함정은 v1식 평면 툴 목록을 그대로 옮겨 역량 경계 없이 툴만 나열하는 경우입니다. 경계가 없으면 재사용도 단위 테스트도 걸리지 않으므로, 이관 첫 단계에서 툴을 도메인별 역량으로 묶고 각 역량에 입출력 계약을 붙여야 합니다. 둘째는 훅과 지침이 역량 밖에 흩어져 프롬프트 회귀를 추적할 수 없는 상태입니다 — 훅을 소유하는 역량을 명시하고, 지침 변경이 어느 역량의 회귀 통과율을 흔드는지 골든셋으로 연결하면 회귀의 출처가 좁혀집니다. 셋째는 베타에서 stable로 넘어오는 사이의 API 변경을 핀 없이 자동 업그레이드하다 프로덕션이 깨지는 경우인데, 복구 분기는 단순합니다. 버전을 정확히 핀으로 고정하고, 업그레이드는 회귀 골든셋을 통과한 뒤에만 승격시키며, 스키마 검증 실패가 임계선을 넘으면 이전 핀으로 되돌립니다.
(다) 운영 체크리스트. 이관은 네 단계로 고정합니다. 먼저 v2 버전을 핀으로 잠그고, 다음으로 역량 경계를 도메인 단위로 정의하며, 각 역량마다 회귀 골든셋을 붙이고, 마지막으로 도그푸딩 단계에서 내부 트래픽으로 먼저 태웁니다. 로그에는 역량 ID, 툴콜 스키마 검증 결과, 소속 훅, 회귀 통과 여부를 필수 필드로 남겨야 역량별 회귀 통과율과 스키마 실패율을 같은 화면에서 대조할 수 있습니다. 도그푸딩은 Pydantic이 자사 레포에서 한 달 돌린 방식 그대로, 위험이 낮은 내부 에이전트 경로부터 적용 범위를 넓혀 갑니다.
(라) 지속 개선 루프. 스프린트마다 이관 커버리지를 갱신하고, 도그푸딩에서 걸러진 스키마 실패 사례를 회귀 골든셋에 역주입합니다. 중복 툴 정의 수가 스프린트를 거치며 줄지 않는다면 역량 경계가 이름만 바뀐 평면 목록이라는 신호이므로, 경계를 다시 그어야 합니다. 개선 루프의 목표 지표는 역량 재사용률 상승분과 커버리지 증가분 두 개면 충분합니다.
한눈에 정리하는 이관 포인트
v2 마이그레이션의 성패는 하네스 우선 구조를 이해하느냐가 아니라 v1의 흩어진 툴·훅·지침을 역량이라는 단일 단위로 다시 조립하느냐에 달려 있습니다. 버전을 핀으로 고정하고, 역량 경계를 도메인별로 정의하고, 역량마다 회귀 골든셋을 붙이고, 도그푸딩으로 내부부터 태우는 네 단계를 지키면, 중복 툴 정의 수는 줄고 이관 커버리지 80%와 스키마 실패율 0.5% 이하라는 합격선이 관측 가능한 숫자로 남습니다.
참고 링크
Pydantic AI v2: capabilities, a leaner core, and the Harness — Pydantic