capability 프리미티브가 묶어내는 것
Pydantic 팀은 2026년 6월 23일 Pydantic AI v2 정식판을 공개했습니다. 핵심은 지침, 도구, 라이프사이클 훅, 모델 설정을 하나의 조합 가능한 단위로 묶는 capability 프리미티브입니다. 지금까지 에이전트마다 따로 붙이던 메모리와 가드레일 같은 확장이 이제 전 계층에서 단일 개념으로 통합되므로, "이 에이전트에는 어떤 가드레일이 붙어 있나"라는 질문의 답이 코드 한 곳으로 모입니다.
harness-first가 코어를 얇게 두는 이유
v2는 루프, 프로바이더, capability·훅 API만 코어에 작게 남기고 나머지 기능은 Harness 계층에 두는 harness-first 구조를 택했습니다. 코어가 얇아지면 프레임워크 버전과 기능 로직의 결합이 느슨해져, 업그레이드가 기능 재작성으로 번지지 않습니다. 이번 판에서는 OpenAI 모델명이 Responses API를 기본으로 쓰도록 바뀌었고 WebSearch·WebFetch가 네이티브로 탑재됐는데, 이런 기본값 변경도 코어가 얇을수록 흡수하기 쉽습니다.
6개월에서 3개월로 좁아진 무중단 창
v2는 메이저 간 무중단 창을 기존 6개월에서 3개월로 단축했습니다. v1 이후 100회 넘는 무파괴 릴리스를 유지해 온 팀이 이 창을 절반으로 줄였다는 것은, 프레임워크 위에 얹은 사내 자산이 3개월 주기로 호환성 점검을 요구받는다는 뜻입니다. 훅과 미들웨어를 버전에 강결합해 둔 조직일수록 이 주기 단축을 그대로 맞기 어렵습니다.
복붙을 모듈로 바꾸는 사내 capability 표준 세우기
기획 단계에서는 성공이 아니라 측정 대상을 먼저 정합니다. 공통 모듈 재사용률(같은 가드레일을 몇 개 에이전트가 임포트해 쓰는가), 가드레일 정책 한 줄을 바꿨을 때 전 에이전트에 반영되는 전파 소요, 메이저 업그레이드 완료까지 걸린 시간을 3대 지표로 둡니다. 출발선은 신규 에이전트의 공통 capability 재사용률 90% 이상, 정책 변경 전파 1일 이내, 업그레이드 소요를 무중단 창의 3분의 1인 30일 이내로 잡는 식이 현실적입니다.
실패는 대개 세 갈래로 옵니다. 첫째, 에이전트마다 가드레일 로직을 복붙해 두면 규정이 바뀔 때 한두 곳을 빠뜨려 정책이 조용히 갈라집니다. 둘째, 훅과 미들웨어를 특정 프레임워크 버전에 강결합해 두면 3개월로 줄어든 무중단 창 안에서 손볼 지점이 코드 전반으로 퍼집니다. 셋째, 업그레이드 창 단축 자체를 일정에 반영하지 않으면 호환성 점검이 릴리스 직전 야근으로 몰립니다.
복구 분기는 표준 모듈 쪽으로 수렴시킵니다. 복붙 흔적이 발견되면 해당 로직을 공통 capability로 승격하고 원본을 임포트로 대체하며, 버전 강결합이 확인되면 훅을 capability API 뒤로 감싸 어댑터 한 겹만 버전에 노출합니다. 무중단 창이 좁아진 데 대응해, 정식판 공개일인 6월 23일 같은 릴리스 시점을 기준으로 호환성 점검 작업을 사전 예약해 두면 마감에 몰리는 일을 줄일 수 있습니다.
운영 체크리스트는 배포 전에 고정합니다. capability마다 소유 팀과 정책 버전을 메타데이터로 남기고, 가드레일 차단·메모리 조회·감사 기록에 동일한 로그 필드(capability ID, 버전, 정책 결과, 마스킹된 입력)를 강제해 어느 에이전트에서 실행됐는지를 한 대시보드에서 추적합니다. PII는 메모리 저장과 감사 로그 양쪽에서 마스킹하고, 새 에이전트를 붙일 때는 세 공통 capability가 실제로 임포트됐는지를 릴리스 게이트로 검사합니다.
지속 개선 루프는 주기 단축에 맞춰 짧게 돕니다. 주간으로 재사용률이 낮은 capability와 여전히 복붙으로 남은 로직 상위 항목을 뽑고, 3개월 창이 닫히기 전에 어댑터 계층의 변경 로그를 기능 코드와 분리해 관리합니다. 자사 공통 capability 3종을 뽑아내는 실습은 다음 순서로 진행합니다. (1) 전체 에이전트에서 가드레일·메모리·감사로그 관련 코드를 수집해 중복 로직을 표로 정렬한다. (2) 정책 결정부와 실행부를 분리해 가드레일 capability의 인터페이스(입력 검사·차단 사유·우회 로그)를 먼저 확정한다. (3) 메모리 capability는 저장 스키마와 조회 범위, 보존 기간, 마스킹 규칙을 하나의 단위로 묶는다. (4) 감사로그 capability는 앞의 두 capability가 남기는 이벤트를 공통 필드로 표준화한다. (5) 세 모듈을 파일럿 에이전트 한 개에 먼저 적용해 전파 소요와 재사용률을 측정한 뒤 전면 이행한다.
한 장으로 보는 이행 포인트
capability는 복붙을 없애는 개념이지 새 프레임워크 자랑거리가 아닙니다. 지침·도구·훅·모델 설정을 한 단위로 묶는 v2의 프리미티브를 빌려, 가드레일·메모리·감사로그 3종을 사내 표준 모듈로 추출하고 재사용률 90%·전파 1일·업그레이드 30일의 합격선을 코드로 선언해 두면, 무중단 창이 3개월로 좁아져도 정책 한 줄 수정이 전 에이전트로 하루 안에 퍼집니다.
참고 링크
Pydantic AI v2: capabilities, a leaner core, and the Harness — Pydantic