AI Agent 서킷 브레이커, 외부 API 장애를 격리하고 안전하게 재개하는 기준
모델 API·CRM·RAG 검색이 연속 실패할 때 무조건 재시도하지 않고, 서킷 브레이커의 차단 범위·상태 전환·시험 호출·대체 흐름을 정하는 실무 기준을 정리합니다.
고객 문의를 분류한 뒤 CRM에 기록하는 Agent가 있다고 해보겠습니다. CRM API가 느려지고 5xx 오류가 이어지는데 워커가 같은 호출을 계속 재시도하면, 실패한 한 연결 때문에 모델 호출·데이터베이스 연결·다른 고객 요청까지 함께 밀릴 수 있습니다.
서킷 브레이커는 이미 실패 가능성이 높은 원격 호출을 잠시 막고 빠르게 다른 경로로 넘기는 장치입니다. 핵심은 오류를 숨기는 것이 아니라, 장애 범위를 격리하고 회복 여부를 제한된 시험 호출로 확인한 뒤 안전하게 재개하는 데 있습니다.
핵심 요약
- 서킷 브레이커는 한 요청의 대기 시간을 끊는 타임아웃이나 일시 오류를 다시 시도하는 재시도와 목적이 다릅니다. 최근 실패 신호를 보고 앞으로의 호출을 잠시 차단합니다.
- Closed·Open·Half-Open 상태를 쓰되, 상태 이름보다 어떤 오류가 차단에 반영되고 어떤 조건에서 시험 호출과 정상 복귀를 허용하는지가 더 중요합니다.
- 브레이커는 “외부 API 전체” 하나로 묶지 말고 공급자·기능·리전·업무 영향처럼 함께 실패하는 경계에 맞춰 나눕니다.
- Open 상태의 행동을 먼저 정합니다. 명시적 실패, 지연 큐, 읽기 전용 축소, 캐시, 사람 인계 중 안전한 경로가 없으면 차단만 추가해도 업무가 완성되지 않습니다.
서킷 브레이커의 목표는 실패를 성공처럼 보이게 하는 것이 아니라, 회복 중인 의존 서비스와 나머지 업무를 함께 보호하는 것입니다.
서킷 브레이커는 타임아웃·재시도·백프레셔와 무엇이 다를까
타임아웃은 이미 시작한 한 호출을 얼마나 기다릴지 정합니다. 재시도는 짧은 일시 오류가 회복될 가능성을 보고 제한된 횟수로 다시 호출합니다. 서킷 브레이커는 최근 실패가 임계값을 넘으면 새 호출 자체를 빠르게 거절해 같은 장애를 반복 확인하지 않게 합니다.
백프레셔는 처리 여력이 줄었음을 입력 단계에 전달해 전체 유입 속도를 늦춥니다. 긴급 중지 버튼은 운영자가 자동화 흐름을 강제로 멈추는 통제입니다. 서킷 브레이커는 특정 의존 서비스나 기능의 건강 상태에 따라 자동으로 열리고 시험적으로 닫히는 더 좁은 장애 격리 장치입니다.
실무에서는 하나가 다른 하나를 대신하지 않습니다. 호출마다 타임아웃이 있고, 재시도는 한 계층에서 제한하며, 반복 장애에는 브레이커가 열리고, 시스템 전체가 포화되면 백프레셔가 입력을 줄이는 식으로 역할을 나눕니다.
먼저 무엇을 함께 차단할지 경계를 정합니다
브레이커가 너무 넓으면 정상 경로까지 막고, 너무 잘게 나누면 상태와 운영 복잡도가 커집니다. “같은 원인으로 함께 실패하며 같은 복구 행동을 쓰는가”를 기준으로 경계를 잡으세요.
- 의존 서비스별: 모델 API, 벡터 검색, CRM, 메일, 결제처럼 장애 원인과 복구 시간이 다른 연결은 분리합니다.
- 기능별: 같은 공급자라도 생성, 임베딩, 파일 변환, 쓰기 API의 한도와 실패 영향이 다르면 별도 브레이커를 둡니다.
- 업무·테넌트별: 한 고객의 잘못된 설정이나 한 리전 장애가 다른 고객과 정상 리전까지 차단하지 않게 범위를 나눕니다.
- 읽기와 쓰기별: 캐시로 대체 가능한 조회와 중복 부수효과가 생기는 CRM 생성·메일 발송은 같은 실패 행동을 쓰지 않습니다.
브레이커 키에는 공급자 이름만 넣지 말고 provider / operation / region / tenant처럼 운영자가 장애 범위를 이해할 수 있는 차원을 기록합니다. 다만 조합을 무제한 늘리기보다 실제 격리와 복구 결정에 쓰는 차원만 남깁니다.
어떤 실패를 차단 신호로 셀지 구분합니다
실패 건수만 세면 업무 오류와 의존 서비스 장애가 섞입니다. 브레이커는 호출 상대가 회복되기 전까지 반복해도 성공하기 어려운 신호를 중심으로 열어야 합니다.
- 연결 실패, 제한 시간을 넘긴 호출, 반복되는 5xx처럼 원격 서비스의 가용성·지연 문제는 후보입니다. 느린 호출 비율을 오류율과 따로 볼 수도 있습니다.
- 429나 명시적 감속 응답은 Retry-After와 공급자 정책을 확인합니다. 곧바로 영구 장애로 단정하지 말고, 재시도 예산과 차단 시간을 해당 신호에 맞춥니다.
- 잘못된 입력, 권한 부족, 승인 누락, 업무 규칙 위반처럼 요청을 고치기 전까지 실패하는 4xx·검증 오류는 별도 처리합니다. 이 오류가 전체 브레이커를 열면 정상 요청까지 막을 수 있습니다.
- 사용자 취소와 전체 업무 데드라인 종료는 호출 상대의 건강 문제와 분리합니다. 취소가 많다는 이유만으로 의존 서비스를 장애로 판단하지 않습니다.
- 메일·결제·CRM 쓰기처럼 응답이 끊겨도 실제 반영 여부가 불명확한 호출은 단순 성공·실패 카운터로 끝내지 않습니다. 업무 키로 원 시스템 상태를 확인한 뒤 재시도나 사람 인계를 결정합니다.
오류 분류는 코드 한 줄보다 운영 계약에 가깝습니다. 공급자 상태 코드, SDK 예외, 업무별 부수효과, 사용자가 보게 될 상태를 표로 만들고 브레이커에 반영되는지 표시하세요.
Closed·Open·Half-Open 상태를 업무 행동으로 번역합니다
Closed: 정상 호출을 허용하고 최근 실패를 관찰합니다
요청을 원격 서비스로 보내되, 일정 관찰 구간의 호출 수·오류 분류·느린 호출·업무 결과를 기록합니다. 우연한 한두 건이 아니라 최소 표본과 실패 비율 같은 조건이 충족될 때 Open으로 전환합니다.
Open: 실패 가능성이 높은 호출을 빠르게 차단합니다
원격 호출을 시작하지 않고 즉시 정해진 대체 행동을 반환합니다. 이때 “성공”으로 포장하지 말고 지연, 기능 축소, 담당자 확인, 다시 시도할 조건을 사용자와 운영자에게 분명히 남깁니다.
Half-Open: 제한된 시험 호출로 회복을 확인합니다
대기 시간이 지난 뒤 소수의 호출만 통과시킵니다. 시험이 연속으로 성공하면 Closed로 돌아가고, 다시 실패하면 Open으로 복귀해 회복 중인 서비스에 전체 대기 요청이 한꺼번에 몰리지 않게 합니다.
Microsoft Azure Architecture Center도 Half-Open 상태에서 제한된 요청만 허용해 회복 중인 서비스가 갑작스러운 요청 폭주로 다시 실패하지 않도록 설명합니다. 상태 전환 이벤트는 운영 지표와 경보에 반드시 남기세요.
임계값은 다른 서비스의 숫자를 복사하지 않습니다
실패 5번처럼 절대 건수 하나만 두면 호출량이 적을 때와 많을 때 의미가 달라집니다. 평시 트래픽, 업무 마감, 공급자 복구 패턴, 허용 가능한 기능 축소 시간을 바탕으로 다음 항목을 함께 정합니다.
- 관찰 구간: 최근 몇 초·몇 분 또는 최근 몇 건을 볼지 정하고, 오래된 실패가 계속 누적되지 않게 합니다.
- 최소 표본과 실패 조건: 호출이 너무 적을 때 우연한 한 건으로 열리지 않도록 최소 호출 수와 오류 비율을 함께 봅니다.
- 느린 호출 조건: 완전한 오류가 아니어도 타임아웃 직전의 지연이 늘면 자원 고갈이 시작될 수 있어 별도 비율로 관찰합니다.
- Open 유지 시간: 고정 숫자보다 실제 복구 시간과 Retry-After, 장애 유형에 맞추고 반복 실패 시 단계적으로 늘릴지 정합니다.
- Half-Open 시험 예산: 허용 호출 수, 동시 실행 수, 필요한 연속 성공, 실패 시 다시 열리는 조건을 정합니다.
초기값은 평시 지표와 장애 주입 시험으로 잡고, 너무 자주 열렸다 닫히는 flapping과 너무 오래 열린 상태를 함께 점검합니다. 임계값을 자동 조정하더라도 왜 상태가 바뀌었는지 운영자가 설명할 수 있어야 합니다.
Open 상태의 대체 행동을 먼저 설계합니다
브레이커가 열렸을 때의 업무 결과가 정해져 있지 않으면 사용자는 빈 화면을 보고 운영자는 실패를 수동으로 찾게 됩니다. 대체 행동은 데이터 신선도와 부수효과를 기준으로 고릅니다.
- 캐시 응답: 조회 결과에만 쓰고, 데이터 기준 시각과 제한된 기능임을 표시합니다. 오래된 가격·재고·권한을 최신처럼 보여주지 않습니다.
- 기능 축소: 선택적 추천·요약·서식 변환은 생략할 수 있지만, 승인·보안·외부 쓰기를 임의로 우회하지 않습니다.
- 지연 큐: 업무 마감 안에 재개 가능하고 중복 방지 키가 있을 때 보류합니다. 무제한 적재 대신 최대 나이와 만료 후 행동을 둡니다.
- 사람 인계: 고객 발송, 결제, 계약, 상태 불명 쓰기처럼 자동 판단 위험이 크면 원인·현재 상태·다음 확인 방법을 함께 넘깁니다.
어떤 대체 경로도 원래 업무와 같지 않다면 성공률에 합치지 마세요. 정상 완료, 기능 축소, 지연, 차단, 사람 인계를 별도 상태로 기록해야 실제 고객 영향을 볼 수 있습니다.
Half-Open 시험과 대기 업무 재개를 분리합니다
시험 호출이 성공했다고 대기열 전체를 즉시 풀면 회복 중인 API를 다시 무너뜨릴 수 있습니다. 건강 확인과 업무 적체 해소는 서로 다른 속도로 진행하세요.
- 시험은 가능한 한 작고 안전한 호출로 만듭니다. 읽기 또는 멱등한 작업을 우선하고, 실제 쓰기가 필요하면 별도 업무 키와 상태 확인 수단을 둡니다.
- Half-Open 동시 실행 수를 제한합니다. 여러 워커가 같은 순간에 시험하지 않도록 공유 상태 또는 리더를 사용합니다.
- 한 번의 성공보다 연속 성공과 지연 회복을 확인합니다. 실패 유형에 따라 바로 Open으로 돌아갈지 추가 표본을 볼지 정합니다.
- Closed로 돌아간 뒤에도 대기 업무는 점진적으로 풀고 새 요청과 오래된 요청의 우선순위·공정성을 함께 적용합니다.
수동 강제 Open·Close가 필요하다면 권한, 사유, 작업자, 만료 시각, 되돌림 절차를 감사 로그에 남깁니다. 운영자가 닫았다는 사실이 의존 서비스의 실제 회복을 보장하지는 않습니다.
업무 시나리오별 서킷 브레이커 적용 예시
고객 문의 요약 뒤 CRM을 갱신하는 Agent
모델 요약과 CRM 쓰기를 별도 브레이커로 둡니다. CRM이 Open이면 문의 원문과 접수 상태는 내부 저장소에 안전하게 남기고, 고객에게 반영 지연을 안내합니다. 재개 전에는 문의 ID로 기존 레코드가 생성됐는지 확인해 중복 쓰기를 막습니다.
사내 RAG 검색과 답변 생성을 연결한 비서
벡터 검색이 Open인데 모델이 일반 지식으로 답하도록 두면 사내 근거가 없는 답을 정상처럼 보여줄 수 있습니다. 검색 장애를 명시하고 답변을 보류하거나, 출처가 확인된 제한 캐시만 사용하며 인용 가능 여부를 별도 상태로 표시합니다.
승인 뒤 메일·메신저를 발송하는 자동화
발송 공급자가 Open이면 승인 자체를 취소하지 말고 승인 유효시간과 발송 보류 상태를 분리합니다. 회복 후 자동 발송할 수 있는지, 유효시간이 지나면 재승인이 필요한지, 상태 불명 발송을 어디서 확인할지 미리 정합니다.
서킷 브레이커가 오히려 장애를 키우는 흔한 이유
- 모든 외부 호출을 전역 브레이커 하나로 묶습니다. 한 모델·리전·고객의 장애가 정상 경로까지 막힙니다.
- 권한·검증·업무 오류를 모두 실패율에 넣습니다. 잘못된 요청이 몰렸다는 이유로 건강한 서비스를 차단하게 됩니다.
- Half-Open에서 한 건 성공하자마자 Closed로 돌립니다. 회복 중인 서비스에 대기 요청이 한꺼번에 다시 몰립니다.
- 캐시나 기본값을 반환하고 정상 성공으로 기록합니다. 장애는 조용히 숨고 오래된 데이터가 실제 업무에 사용됩니다.
- 수동 리셋 권한과 기록이 없습니다. 장애 대응 중 여러 사람이 상태를 바꾸거나, 임시 Open이 영구 설정처럼 남습니다.
라이브러리를 설치했다고 설계가 끝나는 것도 아닙니다. 상태 저장 위치, 여러 워커 간 일관성, 배포 시 초기 상태, 서버리스 인스턴스별 분리, 관측 지표와 대체 흐름을 실제 실행 환경에서 확인해야 합니다.
운영 대시보드에서 함께 볼 지표
- circuit_state / state_transition / trip_reason: 어떤 경계가 왜 열리고 닫혔는지 공급자·기능·리전별로 봅니다.
- allowed / failed / short_circuited_total: 실제 호출, 실패, Open 상태에서 빠르게 차단된 요청을 업무 결과와 분리합니다.
- dependency_latency / timeout / 429 / 5xx: 오류 유형과 느린 호출을 함께 봐 어떤 신호가 상태 전환을 만들었는지 확인합니다.
- half_open_probe / probe_success / reopen_total: 시험 호출 수, 성공률, 다시 열린 횟수로 회복 판단이 너무 빠르거나 느린지 확인합니다.
- open_duration / degraded / queued / manual_handoff: 기술 상태뿐 아니라 기능 축소 시간, 대기 업무 나이, 사람 인계 건수를 고객 영향과 연결합니다.
경보는 한 번 Open이 된 사실만 울리지 말고, 중요한 업무 경계가 열림, Open 시간이 복구 목표를 초과함, 짧은 시간에 반복 전환됨, 대기 업무의 최대 나이가 마감에 접근함처럼 운영 행동이 필요한 조건으로 만드세요.
배포 전 서킷 브레이커 체크리스트
자주 묻는 질문
Q. 재시도를 쓰면 서킷 브레이커는 없어도 되나요?
일시 오류가 짧고 하위 서비스가 재시도 부하를 감당할 수 있다면 제한된 재시도만으로 충분할 수 있습니다. 하지만 실패가 오래가거나 재시도가 자원 고갈과 연쇄 장애를 키운다면 브레이커로 새 호출을 빠르게 차단해야 합니다. 브레이커가 Open임을 알리는 응답에는 재시도를 멈춰야 합니다.
Q. 속도 제한이나 대기열과 같은 기능인가요?
속도 제한은 일정 시간의 요청 수를 제한하고, 대기열은 실행 시점을 늦춥니다. 서킷 브레이커는 최근 실패를 근거로 특정 의존 서비스 호출의 성공 가능성을 판단합니다. 메시지 시스템의 격리·재시도·실패 큐가 충분한 경우에는 별도 브레이커가 불필요할 수 있으므로 현재 플랫폼 기능부터 확인하세요.
HeyRatty와 장애가 번지지 않는 AI 자동화를 설계하려면
HeyRatty는 모델과 도구를 연결하는 데서 끝내지 않고, 의존 서비스별 실패 분류, 타임아웃과 재시도 예산, 서킷 브레이커 경계, 기능 축소, 사람 인계, 운영 지표를 한 흐름으로 정리합니다. 그래야 한 외부 API 장애가 전체 자동화의 장기 지연과 중복 실행으로 번지지 않습니다.
처음부터 모든 연결에 복잡한 상태 기계를 넣을 필요는 없습니다. 가장 자주 멈추는 외부 호출 하나를 골라 “어떤 실패가 반복되는가”, “열렸을 때 업무는 어디로 가는가”, “회복을 몇 건으로 확인할 것인가”부터 적어보세요. 현재 흐름이 복잡하다면 HeyRatty가 작은 장애 주입 테스트와 운영 체크리스트부터 함께 설계할 수 있습니다.
참고 및 이미지 출처
- Microsoft Azure Architecture Center — Circuit Breaker pattern
- AWS Builders' Library — Timeouts, retries, and backoff with jitter
- 이미지 원본: Wikimedia Commons 「USS John C. Stennis sailors conduct training 160105-N-DA737-006.jpg」 · 원 출처 U.S. Department of Defense DVIDS · 촬영 Petty Officer 3rd Class Jonathan Jiang / U.S. Navy · 미국 연방정부 저작물로 미국 내 퍼블릭 도메인 · Commons 제공 1920×1281 JPEG를 직접 사용했습니다. 로컬 생성 이미지 0장.