LLM 에이전트가 조용히 실패하는 이유와 디버깅 방법

에이전트가 빈 결과를 반환했습니다. 예외도 없고, 오류 로그도 없습니다. 유용한 지점을 가리키는 상태 코드도 없습니다. 그저 아무것도 없습니다.

로그를 파헤쳐 봅니다. LLM 호출은 진행되었습니다. 도구(tool)가 호출되었습니다. 응답이 돌아왔습니다. 모든 것이 정상적으로 보이지만, 작업은 미완성이거나 잘못되었거나 완전히 누락되어 있습니다.

이것이 바로 '조용한 실패(silent failure)'입니다. 그리고 이것은 AI 엔지니어링에서 가장 까다로운 버그 중 하나입니다.

LLM 에이전트의 조용한 실패란 무엇인가?

조용한 실패는 에이전트가 예외를 발생시키지 않고 완료되지만, 잘못되었거나 불완전한 결과를 생성하는 경우를 말합니다. 노이즈성 실패(예: Python traceback, API에서 발생하는 5xx 오류)와 조용한 실패의 차이점은, 노이즈성 실패는 디버깅이 가능하다는 것입니다. 반면, 조용한 실패는 무언가 잘못되었다는 것을 알아차리기 위해 전체 에이전트 루프를 계측(instrument)해야 합니다.

조용한 실패가 흔한 이유는 LLM이 항상 무언가를 반환하도록 설계되었기 때문입니다. 모델은 컨텍스트가 부족하거나 도구 스키마가 갑자기 변경되어도 ValueError 같은 것을 던지지 않습니다. 대신 빈 배열, 잘린 JSON 블롭, 또는 아무것도 보여주지 않으면서

해결책: 항상 response.choices, finish_reason, 그리고 usage.completion_tokens를 로그로 남기세요. 만약 finish_reason == "length"라면, 이를 우아한 무작위 동작(noop)이 아닌 명확한 실패(hard failure)로 취급해야 합니다.

도구 스키마 드리프트 (Tool schema drift). 도구 스키마가 변경되는 경우입니다. 필드 이름이 바뀌거나, 필수 파라미터가 삭제되거나, 새로운 열거형(enum) 값이 추가될 수 있습니다. LLM은 이전 스키마에 맞춰 튜닝되었습니다. 이제 LLM은 검증기(validator)를 통과하지 못하는 인자(arguments)를 생성하며, 여러분의 프레임워크는 도구 출력값을 조용히 버리고 계속 진행합니다. LangGraph의 StateGraph는 인터럽트(interrupt) 내부에서 도구가 처리되지 않은 예외(unhandled exception)를 발생시킬 때 정확히 이와 같이 동작합니다. 즉, 출력값은 버려지고 다음 노드는 None을 받게 됩니다.

# 도구가 예외를 발생시키고, StateGraph가 이를 삼켜버림
@tool
def fetch_user_data(user_id: str) -> dict:
...

해결책: 도구 핸들러(tool handlers)에서 항상 예외를 다시 던지거나(reraise), None을 하위 단계로 전달하는 대신 구조화된 에러 페이로드(structured error payload)를 반환하는 명시적인 try/except 문으로 감싸세요.

에이전트 루프 내부의 처리되지 않은 예외 (Unhandled exceptions inside the agent loop). 대부분의 에이전트 프레임워크는 루프를 유지하기 위해 오케스트레이터(orchestrator) 수준에서 예외를 포착(catch)합니다. 이는 신뢰성 측면에서는 좋지만, 단계별 에러가 아무런 유용한 정보도 남기지 않는 포괄적인 핸들러(catchall handler)에 흡수되어 다음 턴이 그대로 진행됨을 의미합니다. 10단계 체인 중 단 한 번의 잘못된 도구 호출이 이후의 모든 단계를 조용히 오염시킵니다.

실패를 조기에 포착하기 위한 단계별 트레이싱(tracing) 추가

조용한 실패를 드러내는 가장 신뢰할 수 있는 방법은 분산 트레이싱(distributed tracing)입니다. 에이전트 단계별 OpenTelemetry 스팬(span)을 사용하면 모든 도구 호출, 입력값, 출력값, 그리고 어디서 실패했는지에 대한 쿼리 가능한 기록을 얻을 수 있습니다.

from opentelemetry import trace

tracer = trace.get_tracer("agent.loop")
...

이제 문제가 발생하면, 트레이스(trace)를 통해 정확히 어떤 단계가 왜 실패했는지 보여줍니다. 흩어진 로그 라인들을 통해 실패 원인을 재구성할 필요가 없습니다. 전체 스팬 트리(span tree)를 갖게 됩니다.

이를 OpenTelemetry 호환 백엔드(Honeycomb, Jaeger, OTel Collector 등)에 연결하면 에이전트 루프에 대한 실시간 가시성을 무료로 확보할 수 있습니다.

조용한 실패를 막는 방화벽으로서의 구조화된 출력 검증 (Structured output validation)

트레이싱 (Tracing)이 무언가 잘못되었을 때를 알려준다면, Pydantic은 모델이 생성한 결과물 중 어떤 것이 당신의 가정을 깨뜨렸는지 알려줍니다.

모든 도구 호출 (Tool call) 뒤에 Pydantic 검증 단계를 배치하세요. 모델의 출력 스키마 (Schema)가 다운스트림 (Downstream)의 다른 요소에 영향을 미치기 전에 검증됩니다. 만약 검증에 실패하면, 5단계나 더 진행된 후 전파되는 조용한 None 값 대신 명확한 메시지가 담긴 ValidationError를 포착할 수 있습니다.

from pydantic import BaseModel, ValidationError

class UserProfile(BaseModel):
...

이는 외부 API를 호출하는 도구에 특히 강력합니다. 외부 스키마는 에이전트의 기대치와 무관하게 독립적으로 변경될 수 있습니다. Pydantic은 경계선 (Boundary)에서 이러한 불일치를 포착하여, 오래된 데이터가 LLM의 다음 프롬프트 (Prompt)로 흘러 들어가 전체 실행 과정을 오염시키기 전에 차단합니다.

장시간 실행되는 에이전트 루프에 데드맨 스위치 (Dead man's switch) 구축하기

장시간 실행되는 에이전트 (수많은 도구 호출을 거치며 몇 분 또는 몇 시간 동안 실행되는 에이전트)에는 루프가 너무 오랫동안 조용해질 경우 작동하는 생존 확인 (Liveness check) 기능이 필요합니다. 만약 에이전트가 N초 이내에 체크인 (Check in)하지 않는다면, 무언가가 에이전트가 작동하지 않는데도 작동 중이라고 가정하고 있는 것입니다.

import threading
import time

...

이것이 트레이싱을 대체하는 것은 아닙니다. 이는 최후의 수단입니다. 만약 당신의 계측 (Instrumentation)이 실패를 놓쳤더라도, 와치독 (Watchdog)은 침묵에 빠진 루프를 여전히 포착하여 알림을 보낼 수 있는 근거를 제공합니다.

FAQ

왜 AI 에이전트는 에러 없이 응답을 중단하나요?

보통 세 가지 중 하나입니다: 모델이 도구 호출 도중에 토큰 예산 (Token budget)에 도달하여 빈 choices 배열을 반환했거나, 도구가 예외 (Exception)를 발생시켰으나 오케스트레이터 (Orchestrator)가 이를 삼켜버렸거나, 또는 도구 출력값이 스키마 검증에 실패하여 조용히 누락된 경우입니다. finish_reason 로깅과 단계별 OTel 스팬 (Spans)을 추가하면 빠르게 원인을 찾을 수 있습니다.

빈 결과를 반환하는 LLM 에이전트를 어떻게 디버깅할까요?

finish_reason부터 시작하세요. 만약 `