로그 분석 노가다를 끝내는 9가지 실패 분류 체계

AI 에이전트의 성공률이 85%에서 70%로 떨어졌을 때, 실무자는 수백 개의 실행 단계인 스팬(span)을 일일이 훑으며 논리 오류 지점을 찾아야 한다. Strands Evals의 Detector는 이 진단 과정을 자동화하여 분석 시간을 시간 단위에서 분 단위로 단축한다.

Detector는 단순한 성공·실패 점수를 넘어 9가지 부모 카테고리로 구성된 실패 분류 체계를 통해 오류의 정체를 식별한다. 분류 항목은 hallucination(환각), incorrect actions(잘못된 행동), orchestration errors(오케스트레이션 오류), task instruction non-compliance(작업 지침 미준수), execution errors(실행 오류), context handling errors(컨텍스트 처리 오류), repetitive behavior(반복 행동), LLM output issues(LLM 출력 문제), configuration mismatch(설정 불일치)로 나뉜다. 이를 통해 에이전트가 정보를 지어냈는지, 도구 호출 파라미터가 틀렸는지, 혹은 작업 지침을 무시했는지를 명확히 구분한다.

분석 결과는 개발자가 즉시 조치할 수 있는 구조화된 데이터로 제공된다. 오류가 발생한 정확한 스팬 위치와 매칭된 카테고리, 분석 결과의 신뢰도 점수, 그리고 트레이스에서 추출한 실제 근거 문장이 함께 제시된다. 개발자는 로그 전체를 읽지 않고 Detector가 짚어준 근거와 위치만으로 문제 원인을 파악할 수 있다.

이런 분류 체계는 수정 방향을 결정하는 기준이 된다. 실행 오류가 많다면 도구 정의를 수정하고, 작업 지침 미준수가 많다면 시스템 프롬프트를 구체화하는 식으로 대응하여 시스템의 어느 부분을 고쳐야 할지 정확한 좌표를 확보하게 된다.

증상과 원인을 분리하는 2단계 분석 파이프라인

Strands Evals의 Detector는 두 단계의 파이프라인으로 작동한다. 첫 번째 단계인 실패 탐지(Failure detection)는 세션 내의 각 스팬을 앞서 언급한 9가지 분류 체계로 스캔하여 문제가 발생한 지점을 빠르게 짚어낸다.

두 번째 단계인 근본 원인 분석(Root cause analysis)은 탐지된 실패들 사이의 인과 관계 체인을 추적한다. 하나의 초기 실수가 연쇄적으로 여러 하위 실패를 일으키는 경우가 많으므로, 시스템은 각 실패의 인과성을 PRIMARY(기본), SECONDARY(이차), TERTIARY(삼차)로 구분하여 계층화한다. 이를 통해 겉으로 드러난 에러라는 증상에 매몰되지 않고, 전체 실패를 촉발한 뿌리 원인을 식별한다.

분석 결과는 구체적인 수정 제안으로 연결된다. 도구의 스키마 오류로 파라미터 검증에 실패했다면 TOOL_DESCRIPTION_FIX(도구 설명 수정)로, 도구 실패 상황에서 에이전트가 환각을 일으켰다면 SYSTEM_PROMPT_FIX(시스템 프롬프트 수정)로 분류하여 실무자가 수정 지점을 빠르게 결정하도록 돕는다.

세션 규모에 따른 처리 전략은 분석 정밀도와 비용의 균형을 맞춘다. 소규모 세션은 직접 분석하고, 중간 규모는 조상과 자손 스팬만 남기는 경로 가지치기(pruning)를 수행한다. 매우 큰 세션은 전체 트레이스를 겹치는 윈도우 단위로 나누어 분석한 뒤 결과를 병합하는 청크 분석(chunked analysis) 방식을 사용하여 LLM의 입력 제한 문제를 해결한다.

Evaluator가 '점수'를 낼 때 Detector는 '방법'을 제시한다

Strands Evals는 성능 측정과 원인 진단을 완전히 분리하여 디버깅 병목을 해결한다. Evaluator는 목표 달성률, 도구 선택 정확도, 도움말 점수 같은 케이스별 점수를 산출한다. 이는 에이전트가 얼마나 잘 작동했는지(How well)를 통계적으로 보여주며, 배포 후나 프롬프트 변경 후 성능 저하 여부를 확인하는 신호등 역할을 한다. 하지만 Evaluator는 점수만 낼 뿐, 구체적으로 어떤 행동이 실패를 유발했는지는 답하지 않는다.

이 지점에서 Detector가 투입되어 왜 실패했는지(Why)를 분석한다. Detector는 개별 스팬 단위로 진단을 수행하고 인과 관계 체인을 추적해 구체적인 수정 제안을 산출한다. 원인과 증상을 분리함으로써 엉뚱한 곳을 수정해 또 다른 버그를 만드는 리스크를 줄인다.

결국 핵심은 디버깅 워크플로의 최적화에 있다. 시니어 엔지니어의 직관과 수동 분석에 의존하던 방식에서 자동화된 진단 파이프라인으로 전환함으로써, 통계적 수치 확인에서 실제 제품 품질 개선으로 이어지는 수정 주기를 단축한다.

diagnosesession 하나로 끝내는 CI/CD 통합 진단

실무자는 `detect_failures` 함수에 세션 객체를 전달해 실패한 스팬 위치와 분류, 신뢰도 점수, 근거를 즉시 확인할 수 있다.

detect_failures(session)

`analyze_root_cause` 함수는 탐지된 실패들 사이의 인과 관계 체인을 추적해 증상과 원인을 분리하고, 수정 지점이 시스템 프롬프트인지 도구 설명인지 가이드를 제공한다.

analyze_root_cause(failures)

개별 함수 호출의 번거로움을 줄이려면 `diagnose_session`을 사용한다. 이 함수는 실패 탐지와 근본 원인 분석을 하나의 파이프라인으로 묶어 중복을 제거한 최종 진단 결과(DiagnosisResult)를 반환한다.

diagnose_session(session)

진단 과정을 CI/CD 파이프라인에 통합하려면 `DiagnosisConfig` 설정을 적용한다. 운영 비용과 목적에 따라 두 가지 트리거 모드를 선택할 수 있다. `ON_FAILURE` 모드는 Evaluator가 `test_pass=False`를 반환할 때만 진단을 실행하여 LLM 호출 비용을 최적화한다. `ALWAYS` 모드는 결과와 상관없이 모든 케이스를 진단하며, 테스트는 통과했지만 효율적이지 않은 경로를 찾아내는 데 유용하다.

Amazon Bedrock 환경의 한국 AI 실무자를 위한 도입 조건

Strands Evals의 Detector는 Amazon Bedrock 및 Strands Agents 기반으로 구축된 에이전트 환경에서 최적화되어 있다. 이를 안정적으로 도입하기 위해서는 몇 가지 기술적 전제 조건이 필요하다.

우선 실행 데이터의 가시성을 위해 OpenTelemetry 트레이싱을 활성화해야 한다. 트레이싱이 활성화된 에이전트 세션은 JSON 형식으로 내보낼 수 있어야 하며, 이를 통해 Detector가 분석할 입력 데이터를 생성한다. 이미 운영 중인 에이전트라면 CloudWatchProvider를 활용하여 저장된 트레이스 데이터를 페치(fetch)해오는 방식으로 분석 환경을 구성할 수 있다. 세부 방법은 Strands Agents SDK의 User Simulation 가이드를 참조한다.

비용 구조를 고려한 운영 전략도 필수적이다. Detector는 내부적으로 LLM을 사용하여 트레이스 데이터를 분석하므로 Amazon Bedrock 모델 사용 비용이 발생한다. 따라서 CI/CD 통합 시에는 `ON_FAILURE` 모드를 기본값으로 설정하는 것이 효율적이다.

마지막으로 대규모 세션 처리 전략을 인프라 설계에 반영해야 한다. Detector가 자동으로 수행하는 직접 분석, 경로 가지치기, 청크 분석이 효율적으로 이루어질 수 있도록, 실무자는 에이전트의 평균 트레이스 길이를 파악하고 모델의 컨텍스트 윈도우 내에서 세션 데이터가 관리되도록 설정해야 한다.

성공률 하락 시 수백 개의 실행 단계를 일일이 확인하던 피로감은 이제 도구의 몫으로 넘길 수 있다. 9가지 실패 분류 체계와 인과 관계 체인을 통해 증상과 원인을 분리하면, 진단 시간은 획기적으로 단축된다.

결국 핵심은 단순한 성능 점수가 아니라 시스템 프롬프트를 고칠지 혹은 도구 설명을 수정할지 결정하는 구체적인 좌표를 갖는 일이다. 이제 `diagnose_session`으로 확보한 진단 결과를 바탕으로 수정 지점을 판단하고 즉시 개선에 착수하면 된다.