DProvenanceKit — AI 에이전트의 추론을 위한 회귀 테스트 및 관측성 (Python, 의존성 없음)
요약
DProvenanceKit은 AI 에이전트의 추론 과정을 기록하고 비교하여 회귀 테스트와 관측성을 제공하는 Python 라이브러리입니다. 의존성 없이 순수 Python 표준 라이브러리만 사용하여 에이전트 실행의 변화를 탐지하고 CI 환경에서 품질을 검증할 수 있게 돕습니다.
핵심 포인트
- 에이전트 실행 경로를 쿼리 및 비교 가능한 트레이스로 변환
- 의존성 없는 순수 Python 표준 라이브러리 구현
- 실행 간 차이 비교를 통한 에이전트 성능 회귀 탐지
- CI 환경에서 에이전트 동작의 안정성을 검증하는 게이트 역할 수행
DProvenanceKit — AI 에이전트의 추론을 위한 회귀 테스트 (regression testing) 및 관측성 (observability) (Python, 의존성 없음)
모든 에이전트 프레임워크는 무엇이 일어났는지 기꺼이 알려줄 것입니다. 여기 토큰이 있고, 여기 도구 호출 (tool calls)이 있으며, 여기 트레이스 워터폴 (trace waterfall)이 있습니다. 하지만 그들 중 거의 어떤 것도 두 실행 사이에서 무엇이 변했는지, 그리고 그 변화가 회귀 (regression)인지 여부는 알려주지 않습니다.
그것이 바로 DProvenanceKit가 채우는 격차입니다. 이 도구는 에이전트의 각 실행을 쿼리 가능하고 차이 비교 (diffable)가 가능한 트레이스로 변환한 다음, 드리프트 (drift)에 실제로 대응할 수 있는 접점을 제공합니다:
실행 (Run) → 기록 (Record) → 쿼리 (Query) → 차이 비교 (Diff) → 회귀 탐지 (Detect regressions) → CI에서 게이트 역할 (Gate in CI)
핵심은 순수 Python 표준 라이브러리입니다. 제3자 의존성 (third-party dependencies)이 전혀 없습니다 (sqlite3, contextvars, threading, json, hashlib).
이는 Swift 라이브러리를 충실하게 포팅한 것이며, 두 라이브러리는 막연한 기대가 아니라 고정된 교차 언어 준수 사양 (cross-language conformance spec)에 의해 동작적으로 동일하게 유지됩니다.
한 가지 예시를 통한 설명입니다. 연구 에이전트 (research agent)가 지원 질문에 답변합니다. 정상적인 "골든 (golden)" 실행은 계획 (plan) → 검색 (search) → 순위 지정 (rank) → 검증 (verify) → 결정 (decide) 과정을 거칩니다. 이후의 PR이 이를 조용히 망가뜨립니다. 에이전트가 검색 도구를 루프 돌리고 검증을 건너뛰게 됩니다. 실행 가능한 하나의 스크립트 (python examples/end_to_end_demo.py)를 통해 모든 계층에서 이를 잡아내는 과정을 확인해 보세요:
── 1. 에이전트의 두 번의 실행 기록 ───────────────────────
golden: 5 단계 ext{['plan', 'search', 'rank', 'verify', 'decide']}
candidate: 8 단계 ext{['plan', 'search', 'search', 'search', 'search', 'search', 'search', 'decide']}
── 2. 의심스러운 패턴 쿼리 (검색은 수행했으나 검증은 수행하지 않음) ──
매칭된 실행: 1건 ext{['research-agent · PR-42']}
── 3. golden 실행 대비 candidate 검증 (Gate) ──────────
판정: REGRESSION (심각도 high, 강도 0.95)
제거된 핵심 단계: ext{['rank', 'verify']}
── 4. 즉시 사용 가능한 이상 징후 규칙 (Out-of-the-box anomaly rules) ───────────────────────
! [tool_drop:verify] 필수 단계 'verify'가 기록되지 않았습니다.
! [looping:search] 'search' 단계가 6회 반복되었습니다 (> 허용치 3회).
── 5. 구조적 차이 (Structural diff) ────────────────────────────────────
rank (Retriever) 제거 @seq 2
verify (Verifier) 제거 @seq 3
search (Retriever) 추가 @seq 2..6
OK — 모든 계층의 일치: candidate가 퇴보함 (verify 누락, search 반복).
이것이 작동하는 이유: 각 실행은 지문(fingerprint), 즉 에이전트 실행 경로의 구조적 정체성을 가집니다. 서로 달라지는(도구가 다른 순서로 호출되거나, 검색 단계가 건너뛰어지는 등) 두 실행은 서로 다른 지문을 생성합니다. 이는 LLM을 루프에 포함하지 않고도 계산할 수 있는 저렴하고 결정론적인(deterministic) 회귀 신호입니다. 단순히
LangChain / LangGraph 어댑터 — 콜백 (callbacks)이 자동으로 스팬 트리 (span tree)가 됩니다.
OpenAI Agents SDK — 한 번의 등록 (store)으로 모든 실행이 캡처됩니다.
프레임워크를 사용하지 않나요? 일반 함수에 @traced 데코레이터를 사용하세요 (동기(sync), 비동기(async), 제너레이터(generators) 모두 작동합니다). 캡처는 결함 방지(failure-proof) 설계로 되어 있어 — 코드의 동작을 변경하거나 예외(exceptions)를 삼키지 않습니다.
from dprovenancekit import InMemoryTraceStore, traced, traced_run, record_event
@traced
def search(query): ...
@traced
def answer(question, sources): ...
with traced_run(store, context_id="ticket-42"):
sources = search(question)
record_event("plan.chosen", {"strategy": "rag"})
reply = answer(question, sources)
패키지에 포함된 다른 기능들: 패리티 스위트 (parity suite)에 의해 동기화된 두 가지 백엔드 (in-memory + WAL SQLite) 상의 단일 쿼리 DSL; 결정론적 재생 (deterministic replay); 부하 차단 (load-shedding)이 조용히 일어나지 않도록 하는 우선순위 인식 백프레셔 (priority-aware backpressure); 공유 가능한 HTML 회귀 보고서 (regression reports); 그리고 8개의 표준 시나리오와 5개의 적대적 (adversarial) 시나리오 전반에서 Precision/Recall/F1 = 1.000을 기록하며 Swift 구현체와 케이스별로 일치하는 검증 코퍼스 (validation corpus). 총 168개의 테스트.
Apache-2.0. SDK와 모든 CI 툴링은 오픈 소스입니다. 대시보드를 원할 경우 별도로 호스팅되는 시각화 도구 (스팬 트리, 페이로드 검사기, side-by-side 시맨틱 디프)가 있지만, 이는 필수가 아닙니다 — 위의 모든 기능은 터미널에서 오프라인으로 실행됩니다.
pip install dprovenancekit
python examples/end_to_end_demo.py # 전체 아크(arc), 자기 검증(self-asserting)
핑거프린팅/얼라이먼트 (fingerprinting/alignment) 모델이나 교차 언어 부합 (cross-language conformance) 접근 방식에 대한 질문은 언제든 환영합니다 — 이 부분이 개발 과정에서 가장 흥미로운 지점이었습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기