Shadow – LangGraph 에이전트를 위한 동작 회귀 테스트 도구
Shadow – behavior regression testing for LangGraph agents
핵심 요약
LangGraph 에이전트의 프롬프트 변경으로 인한 예기치 않은 동작을 방지하고 원인을 분석하는 오픈소스 도구 'Shadow'를 소개함.
- 동작 회귀 테스트 — 에이전트의 프롬프트나 모델 변경 시 발생하는 예기치 않은 동작을 감지함.
- 인과 관계 분석 — 에이전트가 왜 그런 동작을 했는지 추적하여 문제의 원인을 정확히 짚어냄.
- YAML 기반 계약 — 프로덕션과 CI에서 동일하게 작동하는 동작 규칙을 YAML로 정의함.
- 데이터 보안 유지 — 로컬에서 추적 데이터를 관리하여 외부로 데이터가 유출되지 않음.
지난달에 진짜 미치는 줄 알았다.
환불 에이전트를 아주 잘 만들었다고 생각했다. PR에서 프롬프트 딱 하나 살짝 수정했다. 테스트는 통과했고, 코드 리뷰도 통과했다. 그래서 배포했다.
다음 날 프로덕션에서? 에이전트가 확인 절차를 건너뛰고 멋대로 환불을 처리하기 시작했다. 고객들은 난리가 났다. 며칠 동안 로그를 뒤지며 뭐가 문제인지 찾아다녔다.
알고 보니 코드가 바뀐 게 아니었다. 에이전트가 실제로 행동하는 방식이 바뀐 거였다.
이런 '조용한 살인자' 같은 문제 때문에 Shadow를 오픈소스로 공개한다.
Shadow는 LangGraph(및 기타 에이전트 프레임워크)를 위한 동작 회귀 테스트와 인과 관계 기반의 근본 원인 분석을 제공한다. 아주 간단하다:
- 실제 프로덕션과 유사한 트레이스를 로컬 노트북에 보관한다(데이터는 절대 외부로 나가지 않음).
- 에이전트가 어떤 시나리오에서 어떻게 행동해야 하는지 정의하는 YAML 동작 계약을 작성한다.
- PR을 올릴 때마다 다음 명령어를 실행한다:
shadow diagnose-pr
그러면 즉시 다음을 알려준다:
- 에이전트의 실제 행동이 바뀌었는가?
- 정확히 어떤 부분(프롬프트 수정, 모델 교체, 도구 이름 변경 등)이 원인인가?
- 실제 시나리오 중 몇 개가 깨졌는가?
- 통계적 신뢰도와 원인 분석까지 제공한다.
동일한 계약이 프로덕션에서 실시간 가드레일로도 작동한다. CI와 런타임에서 정확히 같은 규칙을 사용한다.
대시보드도 없고, 데이터 업로드도 없다. LangGraph, CrewAI, AG2 등 대부분의 에이전트 프레임워크와 잘 작동한다.
60초 데모 + 퀵스타트: https://github.com/manav8498/Shadow
LangGraph로 개발해 본 사람이라면 이 고통을 알 거다. "사소한" 변경 이후 에이전트에서 가장 자주 깨지는 부분은 무엇인가? 솔직한 피드백 환영한다.
