18장. 도구 에러 핸들링

도구는 반드시 실패한다. 네트워크는 끊기고, 외부 API는 429를 던지고, 데이터베이스는 타임아웃을 내고, 인자는 스키마를 통과해도 의미상 틀린다. 에이전트 시스템에서 신뢰성을 가르는 것은 "실패하지 않는 도구"가 아니라 "실패를 어떻게 모델과 하네스에 전달하고 복구하는가"다. 핵심 원칙은 하나다. 도구 실패는 대부분 모델이 볼 수 있는 결과로 되돌려야 한다. Claude는 도구를 직접 실행하지 않고 호출만 만들어 내므로, 실행 결과를 다시 컨텍스트로 넣어 줘야 모델이 재시도·대체·우회를 판단할 수 있다. 에러를 모델이 보이지 않는 프로토콜 예외로 던지면 모델은 무슨 일이 일어났는지 모른 채 멈추거나 환각한다.

CCA-F의 "도구 설계와 MCP 통합" 도메인(18%) 안에서 에러 핸들링은 단순 try-catch 문제가 아니라 아키텍처 의사결정으로 출제된다. 시험은 "이 에러를 재시도해야 하는가, 즉시 포기해야 하는가", "MCP에서 isError와 JSON-RPC 에러 중 무엇을 써야 하는가", "이 에러 메시지가 왜 모델의 복구를 방해하는가", "장시간 도구의 pause_turn을 어떻게 처리하는가" 같은 판단 문제를 낸다. 멱등성·백오프·서킷 브레이커 같은 분산 시스템 개념이 에이전트 맥락으로 변형되어 나온다는 점이 이 장의 핵심이다.

이 장을 마치면 다음을 할 수 있다.

• 재시도 가능한 에러(429·503·과부하·타임아웃)와 재시도 불가능한 에러(400·401·403)를 구분하고, 지수 백오프와 지터, 멱등성 전제 조건을 적용할 수 있다.
• 도구 실행 실패를 결과 수준 에러로 되돌리는 것과 프로토콜 예외로 던지는 것의 차이를 설명하고, MCP의 isError와 Messages API의 is_error를 정확히 사용할 수 있다.
• pause_turn stop_reason과 장시간 실행 도구의 턴 이어받기를 처리할 수 있다.
• 모델의 자기 복구를 돕는 에러 메시지 설계, 우아한 성능 저하(graceful degradation), 서킷 브레이커, 관측가능성(observability)을 프로덕션 관점에서 적용할 수 있다.