에이전트 시스템의 에러 핸들링: 예외 계층 구조, 부분 결과 및 종료 사유

에이전트 시스템은 전통적인 소프트웨어와는 다른 방식으로 실패합니다. LLM이 파싱할 수 없는 응답을 반환할 수 있습니다. 도구 호출 (tool call)이 타임아웃될 수 있습니다. 에이전트가 무한 ReAct 루프에 빠질 수 있습니다. 인간 검토자가 승인 단계 (approval gate)에서 이탈할 수 있습니다. 작업이 성공하더라도 후속 작업이 사용할 수 없는 출력을 생성할 수도 있습니다.

흥미로운 문제는 이러한 실패를 방지하는 것이 아닙니다. 일부 실패는 비결정론적 시스템 (non-deterministic systems)의 본질적인 특성입니다. 진짜 흥미로운 문제는 운영자에게 이를 우아하게 처리할 수 있도록 충분한 정보를 제공하는 것입니다. 즉, 무엇이 실패했는지, 실패 전까지 무엇이 성공했는지, 그리고 시스템의 최종 상태 (terminal state)가 실제로 무엇인지를 알려주는 것입니다.

예외 계층 구조 (The Exception Hierarchy)

AgentEnsemble은 AgentEnsembleException을 루트로 하는 언체크 예외 (unchecked exceptions) 계층 구조를 사용합니다. 프레임워크가 던지는 모든 예외는 이 기본 클래스를 확장하므로, 단일 catch 블록으로 모든 것을 잡거나 특정 사례를 개별적으로 처리할 수 있습니다.

AgentEnsembleException (base)
  ValidationException             -- 빌드/실행 시점의 잘못된 설정
  TaskExecutionException          -- 실행 중 작업 실패
...

계층 구조가 중요한 이유는 실패 유형에 따라 서로 다른 대응이 필요하기 때문입니다. ValidationException은 설정이 잘못되었음을 의미합니다. 즉, LLM이 호출된 적도 없으며 수정 사항은 코드에 있습니다. TaskExecutionException은 파이프라인이 시작되었으나 작업이 실패했음을 의미하며, 부분 결과 (partial results)를 사용할 수 있을 수도 있습니다. MaxIterationsExceededException은 에이전트가 도구 호출 루프에 갇혔음을 의미하며, 해결 방법은 도구의 수를 줄이거나 반복 제한 (iteration limit)을 높이는 것일 수 있습니다.

실패 시 부분 결과 (Partial Results on Failure)

멀티 태스크 파이프라인이 중간에 실패할 때, 실패 전까지 완료된 작업은 버려지지 않습니다. TaskExecutionException은 실패 전에 완료된 작업들에 대한 TaskOutput 객체 리스트를 포함합니다.

try {
    EnsembleOutput output = ensemble.run(inputs);
    saveResults(output);
...

이는 운영 측면에서 매우 중요합니다. 5개의 태스크로 구성된 파이프라인에서 4번째 태스크가 실패하더라도, 1번부터 3번 태스크까지의 출력값은 여전히 남아 있습니다. 이 결과들을 저장하거나, 사용자에게 보여주거나, 혹은 파이프라인이 중단된 지점부터 다시 재개하는 데 사용할 수 있습니다.

종료 사유 (Exit Reasons)

완료되지 않았다고 해서 모두 에러인 것은 아닙니다. EnsembleOutput.getExitReason()은 네 가지 종료 상태 (terminal states)를 구분합니다.

종료 사유	의미
COMPLETED	모든 태스크가 정상적으로 완료됨
...

EnsembleOutput output = ensemble.run();

switch (output.getExitReason()) {
...

USER_EXIT_EARLY와 TIMEOUT의 구분은 운영 대시보드(operational dashboards)에서 중요합니다. 사용자 종료 (user exit)는 의도적인 것입니다. 즉, 파이프라인은 제 역할을 다했고 사람이 결정을 내린 것입니다. 반면 타임아웃 (timeout)은 프로세스 문제(예: 검토자가 부재중임)를 나타낼 수 있으며, 에스컬레이션 (escalation)이 필요할 수 있습니다.

특정 예외 유형 (Specific Exception Types)

ValidationException (검증 예외)

앙상블 (ensemble) 또는 그 구성 요소가 잘못 설정되었을 때, LLM 호출이 이루어지기 전에 발생합니다. 일반적인 원인으로는 필수 필드 누락, 등록되지 않은 에이전트 (agent)를 참조하는 태스크, 순환 컨텍스트 의존성 (circular context dependencies), 또는 잘못된 반복 제한 (iteration limits) 등이 있습니다.

이 예외는 빌드 타임의 안전망 (build-time safety net) 역할을 합니다. 이 예외가 발생한다면, 해결책은 항상 설정 코드에 있습니다.

AgentExecutionException (에이전트 실행 예외)

LLM 호출 자체에 실패했을 때 발생합니다. 네트워크 오류, API 오류, 속도 제한 (rate limiting), 타임아웃 등이 이에 해당합니다. 실패를 적절한 팀으로 전달할 수 있도록 에이전트의 역할과 태스크 설명을 포함하고 있습니다.

MaxIterationsExceededException (최대 반복 횟수 초과 예외)

에이전트가 ReAct 루프 도중 설정된 maxIterations 제한을 초과했을 때 발생합니다. 설정된 제한 값과 실제 반복 횟수를 모두 포함합니다.

이는 종종 에이전트가 너무 많은 도구 (tools)를 가지고 있어, 진전 없이 도구들 사이를 맴돌고 있다는 신호입니다. 해결 방법은 대개 도구 세트를 줄이거나, 도구 설명을 더 구체적으로 만들거나, 혹은 태스크가 실제로 많은 도구 호출을 필요로 하는 경우 반복 제한을 늘리는 것입니다.

PromptTemplateException (프롬프트 템플릿 예외)

해결되지 않은 {variable} 플레이스홀더(placeholder)가 작업 설명(task description)에 포함되어 있을 때 발생합니다. 이 예외는 누락된 변수 이름을 나열하므로 문제를 쉽게 수정할 수 있습니다.

GuardrailViolationException (가드레일 위반 예외)

입력(input) 또는 출력(output) 가드레일(guardrail)이 실행을 차단할 때 발생합니다. 가드레일 유형(INPUT 또는 OUTPUT), 위반 메시지, 작업 설명(task description), 그리고 에이전트 역할(agent role)을 포함합니다. 이는 이전 포스트에서 다룬 가드레일 시스템과 통합됩니다.

재시도 문제 (The Retry Question)

AgentEnsemble은 내장된 재시도(retry) 로직을 포함하지 않습니다. 이는 의도적인 설계 선택입니다.

그 이유는 재시도 정책(retry policies)이 문맥(context)에 따라 크게 달라지기 때문입니다. 속도 제한(rate-limited)이 걸린 API 호출은 지수 백오프(exponential backoff)를 적용하는 것이 유리할 수 있습니다. 잘못된 형식의 LLM 응답은 동일한 프롬프트로 재시도하는 것이 도움이 될 수 있습니다. 반면, 모델이 요청된 작업을 수행할 수 없어 실패한 작업은 아예 재시도해서는 안 됩니다.

일시적인 실패(transient failures)의 경우, 호출 지점(call site)에서 재시도를 구현하십시오:

int attempts = 0;
EnsembleOutput output = null;

...

운영 환경(production)에서 사용할 경우, 서킷 브레이커(circuit breakers), 속도 제한기(rate limiters), 그리고 예외 계층 구조(exception hierarchy)와 잘 조합되는 재시도 정책을 제공하는 Resilience4j와 같은 회복력 라이브러리(resilience library)를 통합하는 것을 고려하십시오.

운영 모델 (The Operational Model)

에러 핸들링 설계는 에이전트 시스템이 어떻게 운영되어야 하는지에 대한 특정한 관점을 반영합니다. 즉, 실패는 예상되는 것이며, 부분적인 결과(partial results)는 가치가 있고, 프레임워크는 불투명한 에러 문자열 대신 구조화된 정보를 제공해야 한다는 것입니다.

예외 계층 구조를 통해 설정 오류(코드 수정), 일시적 실패(재시도 또는 에스컬레이션), 에이전트 루프(워크플로우 조정), 의도적인 중단(인간의 결정)을 구분하는 모니터링 및 알림(alerting)을 구축할 수 있습니다. 부분 결과 보존(partial result preservation)을 통해 재개 가능한 파이프라인(resumable pipelines)을 구축할 수 있습니다. 종료 사유(exit reasons)를 통해 파이프라인 결과를 정확하게 나타내는 대시보드를 구축할 수 있습니다.

이 중 어느 것도 실패 자체를 막아주지는 않습니다. 다만 실패에 체계적으로 대응할 수 있는 핸들(handles)을 제공할 뿐입니다.

전체 에러 핸들링 가이드는 AgentEnsemble documentation에서 확인할 수 있습니다.

예외 계층 구조 (exception hierarchy)의 세분화 정도가 충분하다고 느끼시는지, 아니면 귀하의 에이전트 시스템에서 이러한 카테고리에 깔끔하게 매핑되지 않는 실패 모드 (failure modes)가 있는지 궁금합니다.