왜 에이전트는 일반 회귀 테스트로 안 잡히나

LLM 에이전트는 같은 입력에도 응답이 흔들리고, 프롬프트 한 줄이나 모델 버전만 바뀌어도 도구 호출 순서가 달라진다. 단위 테스트는 함수 단위 정합성만 보장할 뿐, "실제 사용자 시나리오에서 어제와 다르게 행동하는가"는 잡지 못한다. 그래서 프로덕션에서 쌓인 실제 행동 로그(입력, 도구 호출, 인자, 최종 응답)를 골든셋으로 고정하고, 코드나 프롬프트 변경 후 같은 시나리오를 다시 흘려 차이를 비교하는 리플레이 회귀 테스트가 필요하다.

무엇을 로그로 남길 것인가

리플레이의 품질은 로그 스키마가 결정한다. 최소한 세션 ID, 단계 인덱스, 사용자 입력, 선택된 도구명과 인자, 도구 반환값, 모델 최종 텍스트를 구조화해서 남긴다. 모델 응답 원문(비결정적)과 "행동 결정"(도구 선택·인자, 결정적으로 평가할 부분)을 분리하는 것이 핵심이다.

CREATE TABLE agent_trace (
  session_id   TEXT NOT NULL,
  step         INT  NOT NULL,
  user_input   TEXT,
  tool_name    TEXT,
  tool_args    JSONB,
  tool_result  JSONB,
  final_text   TEXT,
  model        TEXT,
  created_at   TIMESTAMPTZ DEFAULT now(),
  PRIMARY KEY (session_id, step)
);

도구 호출은 반드시 목킹한다

리플레이 시 외부 API·DB를 실제로 다시 호출하면 결과가 매번 달라져 비교 자체가 무의미해진다. 저장된 tool_result를 그대로 돌려주는 목을 주입해, 에이전트가 "같은 관측 아래 같은 판단을 하는지"만 검증한다. 이렇게 하면 테스트가 네트워크와 무관하게 결정적으로 돌아간다.

import json

def load_trace(path):
    with open(path) as f:
        return json.load(f)  # [{step, tool_name, tool_args, tool_result}, ...]

def replay(agent, trace):
    recorded = {(s["step"], s["tool_name"]): s["tool_result"] for s in trace}
    step = {"i": 0}

    def mock_tool(name, args):
        key = (step["i"], name)
        return recorded.get(key, {})  # 저장된 관측을 그대로 반환

    diffs = []
    for s in trace:
        step["i"] = s["step"]
        got = agent.decide(s["user_input"], tool=mock_tool)
        if got["tool_name"] != s["tool_name"] or got["tool_args"] != s["tool_args"]:
            diffs.append({"step": s["step"], "old": s, "new": got})
    return diffs

무엇을 비교할지 – 완전 일치와 의미 일치

도구 선택과 인자는 완전 일치(exact match)로 본다. 반면 최종 자연어 응답은 표현이 달라도 의미가 같을 수 있으므로 임베딩 유사도나 LLM 심판(judge)으로 판정한다. 판정 방식을 항목별로 나눠 관리하면 오탐이 줄어든다.

비교 대상판정 방식회귀로 볼 기준
도구 선택완전 일치다르면 즉시 실패
도구 인자정규화 후 일치핵심 키 불일치 시 실패
최종 응답임베딩/LLM 심판유사도 임계 미만 시 경고

CI에 붙이기

골든 트레이스를 리포지토리나 스토리지에 버전 고정하고, PR마다 리플레이를 돌려 회귀 건수를 리포트한다. 완전 일치 실패는 차단(block), 의미 유사도 저하는 경고로 두면 개발 속도와 안전성이 균형을 이룬다.

replay-regression:
  stage: test
  script:
    - python -m replay --traces traces/golden/ --fail-on tool_mismatch
    - python -m replay --traces traces/golden/ --warn-on text_similarity=0.85
  artifacts:
    when: always
    paths: [reports/replay-diff.json]

주의점

첫째, 골든셋은 살아있어야 한다. 의도한 개선으로 행동이 바뀌면 diff를 검토해 트레이스를 갱신(re-baseline)하는 절차를 명시하라. 그렇지 않으면 팀이 실패를 습관적으로 무시한다. 둘째, 개인정보가 담긴 로그를 그대로 테스트 픽스처로 쓰지 말고 마스킹·샘플링한다. 셋째, 시나리오 커버리지 편향을 주의한다. 로그는 자주 쓰는 경로에 몰리므로, 실패·엣지 케이스 트레이스를 의도적으로 확보해야 실전에서 의미 있는 회귀를 잡는다. 넷째, 모델 버전을 트레이스 메타데이터에 기록해 "모델 교체로 인한 변화"와 "코드 변경으로 인한 변화"를 구분할 수 있게 한다.