핵심 요약

• 타임아웃이나 5xx는 원인이 아니라 결과를 아직 모른다는 신호일 수 있습니다.
• 읽기 전용 조회는 입력과 상태를 다시 확인한 뒤 제한된 예산 안에서 재시도할 수 있습니다.
• 배포·삭제·결제·DB 변경처럼 외부 상태를 바꾸는 호출은, 결과 확인 경로와 중복 방지 장치가 없으면 멈추는 편이 안전합니다.
• 사람 전환은 “오류가 났습니다”라는 알림이 아니라, 다음 판단에 필요한 사건 패킷을 넘기는 일입니다.

재시도 횟수만 정하면 놓치는 것

“실패하면 세 번 재시도”는 시작점으로는 간단하지만, 모든 도구에 같은 규칙을 적용하면 위험해집니다. 검색 API의 조회가 잠시 지연된 경우와 운영 배포 요청의 응답이 끊긴 경우는 겉으로 비슷한 타임아웃이라도 다음 행동이 다릅니다.

조회는 같은 요청을 다시 보내도 대상 상태가 바뀌지 않는 경우가 많습니다. 반면 배포나 레코드 생성은 서버가 이미 작업을 끝냈는데 응답만 잃었을 수 있습니다. 이때 같은 요청을 다시 보내면 두 번 배포하거나 두 개의 레코드를 만들 가능성이 생깁니다.

공식 문서가 말하는 재시도의 범위

Google ADK의 Reflect and Retry 플러그인은 도구 오류를 가로채 모델이 입력을 돌아보고 다시 시도하도록 돕습니다. 시도 횟수와 실패 추적 범위도 설정할 수 있습니다. 이는 파라미터 수정이나 일시적 오류 복구에 유용한 도구이지만, 호출이 외부에 남긴 결과까지 판정해 주지는 않습니다.

Google Developers의 ADK Go 1.0 소개도 Retry and Reflect와 민감 작업의 사람 확인 흐름을 함께 소개합니다. 즉, 자동 회복과 사람의 제어는 서로 대체하는 관계가 아니라 작업 성격에 따라 함께 설계할 경계입니다.

OpenAI의 Errors and recovery 문서는 타임아웃·연결 실패·일시적 서버 오류에서 먼저 저장된 작업과 완료된 행동을 확인하고, 지연과 시도 제한을 둔 뒤 미완료 작업만 계속하라고 안내합니다. 입력 오류, 권한 오류, 한도 오류처럼 원인을 고쳐야 하는 실패를 같은 방식으로 반복하지 않는 점도 중요합니다.

정리하면: 프레임워크의 재시도 기능은 실행 장치이고, 운영 규칙은 “무엇을 다시 해도 되는가”를 정하는 별도 계약입니다.

오류·작업 유형별 판단표

아래 표는 제품별 기본값이 아니라 팀이 자신의 도구 계약에 맞게 채울 수 있는 판단 틀입니다. 화면이 좁을 때는 표를 가로로 넘겨 읽고, 글자가 지나치게 작아지지 않도록 구성하세요.

FLOWIT 6칸 retry·중단 카드 작성법

카드는 재시도를 허용하는 문서가 아니라, 자동 실행의 경계를 드러내는 문서입니다. 도구마다 아래 여섯 칸을 채운 뒤 비어 있는 칸이 있으면 기본값을 “중단”으로 두는 편이 좋습니다.

1. 오류 클래스
   일시적 연결·과부하인지, 입력·권한·한도 문제인지, 혹은 결과가 불명확한지 구분합니다.
2. 가역성·중복 위험
   읽기 전용인지, 되돌릴 수 있는 변경인지, 되돌릴 수 없는 변경인지 적습니다.
3. 시도·시간·비용 예산
   횟수만 두지 말고 마감 시각과 호출 비용까지 함께 둡니다.
4. 입력·상태 재확인
   입력 스냅샷, 요청 식별자, 대상 리소스 버전, 서버 측 결과 조회 방법을 연결합니다.
5. 중단·사람 전환 조건
   예산 소진, 오류 변화, 부분 성공, 권한 경계 도달을 명시합니다.
6. trace·결과 보관 위치
   나중에 같은 실패를 재현할 수 있도록 호출 기록과 결정을 남길 위치를 정합니다.

읽기와 쓰기 타임아웃, 두 가지 사례

사례 1. 읽기 전용 검색이 타임아웃된 경우

에이전트가 내부 문서 검색을 요청했는데 타임아웃을 받았다고 가정해 보겠습니다. 입력 쿼리, 필터, 요청 식별자를 남기고 검색 서비스의 상태나 이전 요청의 완료 여부를 확인할 수 있다면, 짧은 대기 뒤 제한된 예산 안에서 다시 조회할 수 있습니다. 결과가 여러 번 달라지면 “성공”으로 처리하지 말고, 어떤 인덱스·필터·시점의 결과인지 기록해 다음 단계의 판단을 남겨야 합니다.

사례 2. 운영 배포 요청이 타임아웃된 경우

배포 도구가 응답을 돌려주지 않았다고 해서 배포가 시작되지 않은 것은 아닙니다. 먼저 배포 ID, 대상 환경, 변경 버전, 작업 큐와 현재 릴리스 상태를 조회합니다. 중복 방지 키가 없거나 완료 여부를 확인할 경로가 없다면 같은 요청을 자동으로 보내지 않습니다. 사람에게 넘기고, 확인 뒤에만 새 작업을 만들거나 롤백을 검토합니다.

재시도 전에 확인할 체크리스트

• 이 호출은 읽기 전용, 가역 쓰기, 비가역 쓰기 중 어디에 속하나요?
• 중복 방지 키 또는 중복 실행을 막는 서버 측 계약이 있나요?
• 이전 요청 식별자와 서버 측 결과를 조회할 수 있나요?
• 남은 시도·시간·비용 예산은 얼마인가요?
• 부분 성공 가능성이 있다면 누가 어떤 근거로 다음 행동을 결정하나요?

중단 뒤 사람에게 넘길 사건 패킷

사람 전환은 자동화를 포기하는 것이 아닙니다. 사람이 처음부터 로그를 뒤지지 않고 안전하게 판단하도록, 필요한 정보를 압축해 넘기는 운영 단계입니다.

반복되는 실패는 묻어두지 말고, 민감 정보는 제외한 재현 가능한 사례로 분리해 평가에 반영할 수 있습니다. 실패 trace를 재발 방지 테스트로 바꾸는 방법은 실패 trace를 회귀 테스트로 바꾸는 5칸 원장에서 이어서 확인해 보세요.

다음으로 연결할 운영 경계

• 모델 서비스 장애 때 다른 모델로 전환해야 한다면 fallback 품질을 같게 만드는 5개 테스트를 함께 확인하세요.
• 오류가 나기 전에 민감 도구의 실행 권한을 구분하려면 실행 시점 허가를 설계하는 3패턴·6문항이 도움이 됩니다.
• 도구 결과를 안전하게 재현하려면 도구 결과를 고정하는 6칸 계약으로 이어갈 수 있습니다.

자주 묻는 질문

타임아웃이면 무조건 재시도해도 되나요?

아닙니다. 결과가 이미 발생했는지 확인할 수 있는지와 작업의 중복 실행 위험을 먼저 확인해야 합니다. 결과가 불명확한 쓰기 작업은 상태 확인이 우선입니다.

중복 방지 키가 있으면 항상 안전한가요?

중복 실행을 줄이는 중요한 장치이지만, 적용 범위·보존 기간·서버 측 결과 조회 경로까지 함께 확인해야 합니다. 호출자와 서버가 같은 키를 어떤 의미로 처리하는지도 계약으로 남기세요.

읽기 작업은 몇 번까지 재시도하면 되나요?

고정 횟수보다 서비스가 요구하는 대기 시간, 남은 마감 시간, 호출 비용과 중요도를 반영한 시도·시간 예산을 두는 편이 안전합니다. 오류가 바뀌거나 예산이 소진되면 중단합니다.

사람에게 넘길 때 무엇을 남겨야 하나요?

입력과 권한 범위, 요청 식별자, 오류, 시도 기록, 확인한 상태, 이미 변경됐을 가능성, 권장 다음 행동을 함께 남기세요. 비밀값이나 필요 이상의 원문 대화는 포함하지 않습니다.