AI 에이전트 디버깅 체크리스트: 실패한 실행에서 근본 원인 파악까지

프로덕션 환경에서 AI 에이전트가 실패했을 때, 가장 먼저 드는 생각은 보통 프롬프트 (Prompt)를 수정하고 워크플로 (Workflow)를 다시 실행하는 것입니다.

하지만 이는 사고를 이해하기 더 어렵게 만들 수 있습니다.

재실행 시 모델 출력 (Model output), 검색된 컨텍스트 (Retrieved context), 도구 상태 (Tool state), 타이밍 (Timing), 권한 (Permissions) 또는 외부 API 응답이 변경될 수 있습니다. 만약 에이전트가 이미 이메일을 보냈거나, 환불을 처리했거나, 티켓을 변경했거나, MCP 도구를 호출했다면, 단순한 재실행은 부작용 (Side effect)을 반복할 수도 있습니다.

더 나은 워크플로는 무엇인가를 변경하기 전에 실패한 실행의 증거를 보존하는 것부터 시작됩니다.

이 체크리스트는 도구 (Tools), 검색 (Retrieval), 메모리 (Memory), 워크플로 (Workflows) 또는 외부 API를 사용하는 프로덕션 AI 에이전트를 디버깅하는 개발자를 위한 것입니다. 목표는 모든 실행을 결정론적 (Deterministic)으로 만드는 것이 아닙니다. 목표는 첫 번째로 지원되지 않는 결정을 찾아내고, 실패를 재현 가능한 회귀 (Replayable regression)로 만드는 것입니다.

1. 실행 식별자 캡처 (Capture the run identity)

실패한 실행을 다시 찾을 수 있는지 확인하는 것부터 시작하세요.

다음 사항을 기록하십시오:

트레이스 ID (Trace ID) 또는 실행 ID (Run ID)
사용자/세션/작업 ID (User/session/job ID)
에이전트 버전 (Agent version)
배포 SHA (Deployment SHA)
모델 및 제공업체 (Model and provider)
프롬프트 또는 지침 버전 (Prompt or instruction version)
도구 레지스트리 버전 (Tool registry version)
검색 인덱스 버전 (Retrieval index version)
환경 및 지역 (Environment and region)
타임스탬프 및 시간대 (Timestamp and timezone)

이것이 없다면 사고 검토는 고고학 작업이 됩니다. 스크린샷과 복사된 로그만으로는 충분하지 않습니다. 팀에는 모델 호출 (Model calls), 도구 호출 (Tool calls), 애플리케이션 로그 (Application logs), 큐 작업 (Queue jobs) 및 외부 API 쓰기 (External API writes)를 연결할 수 있는 안정적인 식별자가 필요합니다.

2. 원래 트리거 및 컨텍스트 보존 (Preserve the original trigger and context)

동일한 사용자 요청이라도 컨텍스트 (Context)에 따라 다른 동작을 생성할 수 있습니다.

다음 사항을 캡처하십시오:

원래 사용자 입력 또는 작업 페이로드 (Original user input or job payload)
실행 시 활성화된 시스템/개발자 지침 (System/developer instructions)
검색된 문서 또는 청크 (Retrieved documents or chunks)
에이전트가 사용한 메모리 항목 (Memory entries)
계정, 테넌트, 역할 및 권한 범위 (Account, tenant, role, and permission scope)
실행 전 관련 제품 상태 (Relevant product state)
기능 플래그 및 라우팅 결정 (Feature flags and routing decisions)

흔한 실패 패턴 중 하나는 불완전하거나 오래된 컨텍스트 (Context)를 바탕으로 그럴듯한 모델 답변을 생성하는 것입니다. 최종 응답만을 검사한다면 에이전트가 비합리적으로 보일 수 있습니다. 하지만 에이전트가 실제로 본 컨텍스트를 검사하면 실패 원인이 명확해지는 경우가 많습니다.

3. 출력뿐만 아니라 결정을 검사하십시오

에이전트의 경우, 중요한 질문은 종종 "모델이 무엇이라고 답변했는가?"가 아니라 "에이전트가 왜 이 다음 행동을 선택했는가?"입니다.

다음 사항을 확인하십시오:

선택된 도구 (Tool) 또는 분기 (Branch)
에이전트가 선택할 수 있었던 대안들
실행된 가드레일 (Guardrails) 또는 정책 체크 (Policy checks)
실행되었어야 하지만 실행되지 않은 가드레일 또는 정책 체크
누락된 사실
요약 또는 검색된 콘텐츠에 의해 도입된 가정 (Assumptions)
에이전트 간 또는 워크플로 단계 간의 핸드오프 (Handoffs)

잘못된 최종 응답은 눈에 보입니다. 하지만 잘못된 중간 결정은 최종 응답이 멀쩡해 보이는 동안 숨겨져 있을 수 있습니다.

4. 도구 호출을 모델의 결정과 API 이벤트의 결합으로 취급하십시오

도구 호출 (Tool calls)은 에이전트 디버깅이 일반적인 요청 추적 (Request tracing)과 갈라지는 지점입니다.

각 도구 호출에 대해 다음을 보존하십시오:

도구 이름 및 스키마 (Schema)
생성된 인자 (Arguments)
검증 결과 (Validation result)
권한 또는 인증 범위 (Permission or auth scope)
가공되지 않은 도구 응답 (Raw tool response)
정규화된 도구 응답 (Normalized tool response)
지연 시간 (Latency) 및 타임아웃 (Timeout) 동작
재시도 횟수 (Retry count)
에러 페이로드 (Error payloads)
외부 변동 (External mutation) 또는 영구 영수증 ID (Durable receipt ID)

도구 호출은 API 경계에서는 "성공"할 수 있지만, 여전히 잘못된 행동일 수 있습니다. 도구 엔드포인트는 200을 반환했지만, 에이전트는 여전히 잘못된 환불을 처리하거나, 잘못된 계정을 조회하거나, 불완전한 응답을 신뢰하거나, 쓰기 작업을 재시도했을 수 있습니다.

5. 읽기 전용 도구와 변동 도구를 분리하십시오

모든 도구를 동일한 방식으로 디버깅하지 마십시오.

각 도구를 다음과 같이 분류하십시오:

읽기 전용 (Read-only)
쓰기 (Write)
위험한 쓰기 (Risky write)
사람의 승인 필요 (Human approval required)
외부 부작용 (External side effect)

변동 도구 (Mutating tools)의 경우, 전/후 상태 (Before/after state)와 멱등성 키 (Idempotency key)를 캡처하십시오. 이메일, 티켓, 환불, 데이터베이스 쓰기, 캘린더 변경 및 외부 워크플로 업데이트의 경우 영구 영수증 (Durable receipt)을 캡처하십시오.

핵심 재생 규칙: 디버깅은 운영 환경의 부작용 (Side effects)을 반복해서는 안 됩니다.

6. 모델을 탓하기 전에 검색 (Retrieval) 및 메모리 (Memory) 확인하기

많은 에이전트 실패는 컨텍스트 (Context) 실패입니다.

다음 질문을 던져보십시오:

검색 (Retrieval)이 올바른 소스를 반환했는가?
소스가 오래된(Stale) 정보였는가?
청킹 (Chunking) 또는 요약 (Summarization) 과정에서 관련 사실이 누락되었는가?
메모리 (Memory)가 오래된 사용자 선호도나 구식 상태 (Obsolete state)를 도입했는가?
에이전트가 실제로 존재하지 않는 증거를 인용하거나 의존했는가?
이후의 도구 (Tool) 결과가 이전에 검색된 컨텍스트와 모순되는가?

만약 모델에 잘못되었거나 불완전한 증거가 제공되었다면, 프롬프트 튜닝 (Prompt tuning)은 시스템을 고치지 못한 채 증상만을 숨길 수 있습니다.

7. 실패한 실행을 성공적인 실행과 비교하기

적절한 비교는 수 시간을 절약해 줄 수 있습니다.

다음 항목들을 비교하십시오:

동일한 사용자 의도 (User intent), 다른 결과
동일한 도구 (Tool), 다른 인자 (Arguments)
동일한 검색 쿼리 (Retrieval query), 다른 청크 (Chunks)
동일한 워크플로우 분기 (Workflow branch), 다른 가드레일 (Guardrail) 결과
동일한 외부 API (External API), 다른 권한 범위 (Permission scope)
동일한 프롬프트 버전 (Prompt version), 다른 모델/제공자 (Model/Provider) 응답

목표는 의미 있는 첫 번째 차이점 (Divergence)을 찾는 것입니다. 타임라인 (Timelines)은 순서를 보여줍니다. 결정 그래프 (Decision graphs)는 인과 관계 (Causality)를 보여줍니다.

8. 재실행하기 전에 재생 (Replay)을 안전하게 만들기

재생 (Replay)이 모든 토큰을 정확하게 다시 생성해야 한다는 의미는 아닙니다. 이는 규율 있는 질문을 던질 수 있을 만큼 충분한 증거를 보존한다는 것을 의미합니다.

재생하기 전에, 다음 항목들을 고정 (Pin)하거나 스텁 (Stub) 처리하십시오:

사용자 입력 (User input)
프롬프트/지침 (Prompt/instruction) 버전
검색된 컨텍스트 (Retrieved context)
도구 출력 (Tool outputs)
외부 API 응답 (External API responses)
현재 시간 (Current time)
무작위 ID (Random IDs)
상태를 변경하는 도구 동작 (Mutating tool behavior)
비식별화 (Redaction) 후의 비밀 값 및 민감한 필드 (Secrets and sensitive fields)

안전한 재생을 통해 팀은 또 다른 이메일을 보내거나, 티켓을 생성하거나, 환불을 처리하거나, 운영 상태 (Production state)를 변경하지 않고도 수정 사항이 실패한 결정을 바꾸는지 테스트할 수 있습니다.

9. 인시던트를 회귀 테스트 (Regression)로 전환하기

근본 원인 (Root cause)을 찾은 후에는 증거를 보관하십시오.

다음 항목을 포함하는 회귀 테스트 픽스처 (Regression fixture)를 생성하십시오:

최소한의 실패 입력 (Minimal failing input)
고정된 컨텍스트 (Pinned context)
예상되는 결정 또는 차단된 동작 (Expected decision or blocked action)
도구 출력 스텁 (Tool output stubs)
부작용 (Side effects)에 대한 단언 (Assertions)
근본 원인에 대한 노트
운영 트레이스 (Production trace)로의 링크

훌륭한 회귀 테스트 피스처 (Regression fixtures)는 향후 프롬프트 변경, 모델 업그레이드, 검색 (Retrieval) 변경 또는 도구 스키마 (Tool schema) 수정으로 인해 동일한 유형의 실패가 다시 발생하는 것을 방지합니다.

10. 짧은 사고 리뷰 템플릿을 사용하세요

에이전트를 위한 유용한 사고 후 리뷰 (Post-incident review)는 간단할 수 있습니다:

사고 (Incident): 무슨 일이 일어났는가?
영향 (Impact): 누구 또는 무엇이 영향을 받았는가?
첫 번째 지원되지 않는 결정 (First unsupported decision): 에이전트가 어디서 잘못되었는가?
...

"첫 번째 지원되지 않는 결정" 항목이 중요한 부분입니다. 이 항목은 리뷰가 "모델이 환각 (Hallucination)을 일으켰다" 또는 "프롬프트가 나빴다"와 같은 모호한 진술로 흐르는 것을 막아줍니다.

빠른 체크리스트

프롬프트나 코드를 변경하기 전에 다음 사항을 캡처하세요:

맺음말

운영 환경의 에이전트 디버깅 (Production agent debugging)은 예쁜 트레이스를 관찰하는 것이 아니라, 결정 뒤에 숨겨진 증거를 보존하는 것에 더 가깝습니다.

에이전트가 무엇을 보았는지, 무엇을 선택했는지, 무엇이 변했는지, 그리고 어떻게 안전하게 재생 (Replay)할 수 있는지를 답할 수 있다면 실패를 디버깅할 수 있습니다. 만약 답할 수 없다면, 당신은 추측하고 있는 것입니다.

유용한 관련 리소스:

AI agent 디버깅 가이드: https://www.opswald.com/ai-agent-debugging/
AI agent 리플레이: https://www.opswald.com/ai-agent-replay/
툴 호출 실패 디버깅: https://www.opswald.com/debug-tool-calling-failures/
에이전트 디버깅 플레이북: https://github.com/opswald/agent-debugging-playbook