AI 에이전트의 스냅샷 테스트를 위한 EvalView

AI 에이전트의 스냅샷 테스트.

오늘 여러분의 에이전트가 무엇을 하는지 기록하세요. 그리고 그것이 조용히 변경될 때 알림을 받으세요.

여러분의 에이전트는 200 상태 코드를 반환하며 정상적으로 보입니다. 하지만 모델 업데이트, 제공업체(provider) 변경, 또는 한 줄의 프롬프트 편집만으로도 명확화 과정을 건너뛰거나, 잘못된 도구(tool)를 호출하거나, 출력 품질을 조용히 떨어뜨릴 수 있습니다. 여러분의 테스트는 여전히 통과합니다. 하지만 사용자들은 여러분보다 먼저 알아차립니다.

EvalView는 에이전트가 사용하는 동작 — 즉 어떤 도구를 어떤 순서로, 어떤 출력과 함께 호출하는지 — 를 스냅샷으로 기록하고, 그 행동이 변경되는 순간을 알려줍니다. Jest의 스냅샷 기능처럼 작동하지만, 이는 도구 호출(tool-calling) 및 다중 턴 에이전트(multi-turn agents)에 특화되어 있습니다.

demo.mp4

↑ API 키가 필요 없는 30초 라이브 데모

OpenAI 어댑터 마이그레이션: OpenAI는 2026년 8월 26일부로 Assistants API를 중단합니다. 최신 버전의 EvalView인 0.8.1도 여전히 해당 API를 사용하고 있으므로, Responses API로의 마이그레이션은 현재 미공개 소스입니다. 만약 openai-assistants를 사용한다면, 테스트를 실행하기 전에 마이그레이션 가이드를 따르세요. 단순히 assistant_id만으로는 에이전트의 구성을 보존할 수 없습니다. 다른 어댑터들은 영향을 받지 않습니다.

pip install evalview

evalview snapshot # 에이전트의 현재 동작을 기준선(baseline)으로 기록합니다.
evalview check # 변경 사항 발생 후, 기준선과 비교(diff)합니다.

이것이 전체 루프입니다. check는 다음 중 하나를 반환합니다:

✓ login-flow PASSED behavior matches baseline
⚠ refund-request TOOLS_CHANGED called a different tool, or in a different order
✗ billing-dispute REGRESSION score dropped — output quality fell

이는 최종 문자열(string)뿐만 아니라 전체 궤적(whole trajectory) — 도구 이름, 매개변수(parameters), 순서 — 를 비교합니다. 결정론적인 도구 및 시퀀스 비교는 오프라인에서 API 키 없이 실행됩니다. 출력 품질 점수화가 필요할 때만 LLM judge를 추가하세요.

에이전트를 실행하는 것 자체로도 백엔드 API 요금이 발생할 수 있습니다: --no-judge 옵션은 judge 호출을 건너뜁니다. 임베딩 기반의 의미론적 비교(semantic comparison)는 선택 사항입니다.

아직 에이전트가 없나요? 30초 만에 작동하는 것을 확인해 보세요:

evalview demo

대부분의 평가 도구는 사용자에게 '무엇이 좋은지'를 직접 작성하도록 요구합니다. 즉, 단언(assertions), 지표(metrics), 루브릭을요. 이는 많은 사전 작업량을 필요로 하며, 사용자가 단언할 것이라고 생각한 실패 사례만 포착할 수 있습니다.

EvalView는 이를 역전시킵니다. 현재 에이전트가 실제로 무엇을 하는지 기록하고, 그 행동에서 벗어나는 모든 변화(drift)를 플래그합니다. 아무런 단언도 작성하지 않고도 예상치 못한 회귀(regressions)를 포착할 수 있습니다. 새로운 동작이 올바르면, evalview snapshot 명령어가 이를 새로운 기준선(baseline)으로 받아들입니다. 이는 Jest에서 스냅샷을 업데이트하는 것과 같습니다.

매일 09:00 UTC에 풀 리퀘스트 및 main 브랜치 푸시 시마다,
Core Dogfood가 비실시간 테스트 스위트, 타입 검사, 로컬 모의 에이전트 snapshot
/ check
, evalview demo
, 엔드투엔드(end-to-end) 흐름, 그리고 evalview monitor
스모크 테스트를 수행합니다. 이는 유료 API 자격 증명을 사용하지 않으며 유료 추론 호출을 발생시키지 않습니다. GitHub 러너 사용은 별개입니다.

Live Provider Checks는 유지 관리자가 main 브랜치에서 유료 API 사용에 명시적으로 동의할 때만 실제 평가기 및 채팅 비서에 대한 테스트를 수행합니다. 이들은 자동 스케줄이 없습니다. 해당 배지는 마지막 수동 실행을 기록하며, 녹색 Core 배지가 라이브 프로바이더의 상태를 보장하거나 프로바이더 드리프트를 배제하지는 않습니다.

패키지 CI, core dogfood, 그리고 라이브 검사는 각각 별도의 배지를 가집니다. 실패했거나 불완전한 검사는 해당 범위 내에서 계속 표시되며, 로그와 보고서는 아티팩트로 보존됩니다. 롤링 이슈(Rolling issues)는 별도의 dogfood-core 및 dogfood-live 레이블을 사용합니다.

프로바이더 서비스 중단, 할당량 소진 또는 누락된 자격 증명은 라이브 상태를 사용할 수 없음을 의미하며, 에이전트 회귀를 증명하지는 않습니다.

과거 인시던트 #264는 두 범위(scope) 모두에서 새로 확보된 증거를 유지 관리자(maintainer)가 검토할 수 있도록 계속 이용 가능합니다. 어떤 워크플로우도 이를 자동으로 종료하지 않습니다. 신뢰 경고(Trust warnings)는 조사를 위한 증거일 뿐, 게임을 했거나 특정 근본 원인(root cause)의 증거는 아닙니다.

Core runs → · Manual live runs → · Run and triage guide →

# .github/workflows/evalview.yml
name: EvalView
on: [pull_request]
...

PR 댓글을 통해 diff, 비용/지연 시간 변화량(cost/latency deltas), 그리고 통과/실패 게이트를 받게 됩니다. CI/CD 가이드 →

LangGraph · CrewAI · OpenAI · Claude · Mistral · Ollama · MCP · 모든 HTTP API.

evalview check --agent http://localhost:8000/invoke

from evalview import gate
result = gate(test_dir="tests/")
result.passed # bool
...

EvalView는 또한 다중 턴 테스트, 통계적/pass@k 실행, 기록/재생 카세트(record/replay cassettes), 모델 드리프트 캐나리아(model-drift canaries), Slack 알림을 통한 프로덕션 모니터링, 인시던트로부터의 자동 생성된 회귀 테스트를 수행합니다. 이들은 파워 유저 기능이므로, snapshot과 check부터 시작하고 필요할 때 나머지 기능을 활용하십시오.

→ 전체 기능 참고 자료 · 시작하기 · FAQ

→ 문서 색인 · OpenAI 마이그레이션 · 릴리스 프로세스

성공적으로 보였던 에이전트가 전체 문서를 컨텍스트로 계속 가져와서, 단 하나의 질문에 $42.93의 비용을 발생시킨 적이 있습니다. 그 경험이 저에게 EvalView를 만들게 했습니다. 저는 이 내용을 “AI 카지노를 운영하다. 그리고 내 에이전트를 위한 테스트 작성을 시작했다”라는 글에서 다루었습니다. 2025년 12월 게시물이 기원 이야기이며, 설정 및 명령어는 현재 문서를 사용하십시오.

이것은 주로 한 개발자에 의해 만들어진 초기 프로젝트입니다. 이슈(Issues), PR, 그리고 “사용해 봤는데 X가 혼란스러웠다”와 같은 피드백 모두 진정으로 가치가 있습니다.

라이선스: Apache 2.0