AI 에이전트 실행 로그 읽는 법 — 실패 원인 추적하기

AI 에이전트가 “완료했습니다”라고 답했는데 파일이 없거나, 같은 검색을 반복하며 비용만 늘어날 때가 있습니다. 최종 답변만 저장하면 어느 단계가 잘못됐는지 알 수 없습니다. 에이전트의 한 번의 목표는 여러 모델 호출과 도구 실행으로 이어집니다. 전체 흐름을 연결한 로그를 남겨 어느 단계가 잘못됐는지 확인하세요.

최소한 이 8가지는 기록하세요

필드	기록 목적
`run_id`	한 번의 업무 전체를 연결
`step`	실행 순서 확인
`tool`	선택한 도구 확인
`input_summary`	민감정보를 제외한 입력 요약
`result_status`	성공·실패·승인 대기 구분
`error_code`	같은 오류 반복 확인
`usage`	단계별 토큰·도구 사용량 확인
`started_at/duration`	지연과 타임아웃 확인

원문 입력과 도구 결과를 모두 저장하면 디버깅은 편하지만 개인정보와 기밀이 로그에 복제될 수 있습니다. 기본 로그에는 요약과 식별자만 남기고, 원문 접근은 별도 권한과 보존 기간으로 관리하세요.

실행 로그 예시

다음은 교육용 가상 로그입니다. 실제 실행·성능 측정 기록이 아니며, 필드 이름도 특정 SDK의 원본 형식이 아닌 설명용입니다. null은 측정하지 않았다는 뜻으로 0이나 성공으로 해석하지 않습니다.

run_id=example-weekly-report
step=1 call_id=read-01 tool=analytics.read status=success
step=2 call_id=write-01 tool=spreadsheet.write status=approval_required
step=3 call_id=write-01 approval=approved reviewer=role:team-lead
step=4 call_id=write-01 tool=spreadsheet.write status=success
step=5 call_id=mail-01 tool=email.send status=blocked reason=missing_final_review
usage.input_tokens=null usage.output_tokens=null duration_ms=null

같은 write-01이 승인 대기→승인→실행으로 이어집니다. 실제 구현에서는 ID만 같다고 승인된 것으로 보지 말고 도구·대상·인수와 승인 범위를 함께 검증합니다. 인수가 바뀌었다면 이전 승인을 재사용하지 않습니다.

이 로그에서는 에이전트가 메일을 보내지 못한 것이 오류가 아니라 최종 검토 규칙이 정상 작동한 결과임을 알 수 있습니다. 실패와 정책 차단을 같은 상태로 기록하면 불필요한 재시도가 생길 수 있습니다.

자주 발생하는 실패 패턴 네 가지

같은 도구를 반복 호출

동일한 입력과 오류 코드가 연속해서 나타나면 재시도 상한과 대체 경로가 없는지 확인합니다. 인증 오류처럼 다시 시도해도 해결되지 않는 오류는 즉시 사람에게 넘겨야 합니다.

도구는 성공했지만 목표는 실패

파일 저장 도구가 성공해도 잘못된 폴더에 저장했다면 업무는 실패입니다. 도구 반환값뿐 아니라 최종 파일 경로·행 수·변경 건수 같은 완료 조건을 확인합니다.

승인 후 입력값이 달라짐

승인 화면에서 본 대상과 실제 실행 대상이 같은지 호출 ID로 연결해야 합니다. 승인 뒤 모델이 인수를 새로 만들지 않도록 승인된 호출 자체를 재개하는 구조가 필요합니다.

비용이 특정 단계에서 급증

입력 토큰이 긴 단계, 검색 결과가 과도한 단계, 재시도가 많은 단계를 분리해 봅니다. 비용 계산은 AI API 비용 계산법을 참고하세요.

기대 결과·실패 징후·확인 순서

기대 결과: 하나의 run_id로 목표 수신부터 종료까지 순서가 이어지고, 사람 승인과 실제 도구 실행이 연결됩니다.

실패 징후: 단계 번호가 끊기거나, 승인한 도구와 실행된 도구가 다르거나, 민감한 원문이 로그에 그대로 남거나, 같은 오류가 제한 없이 반복됩니다.

확인 순서

마지막 성공 단계와 첫 실패 단계를 찾습니다.
도구 입력·권한·오류 코드를 확인합니다.
같은 입력의 재시도 횟수를 셉니다.
승인 대상과 실행 호출 ID를 대조합니다.
완료 조건을 충족했는지 별도로 확인합니다.

이 로그를 보고 다음 행동 결정하기

이 예시에서 파일 저장은 성공했지만 메일 발송까지 포함한 업무 전체는 완료되지 않았습니다. 실행 상태를 검토 대기로 남기고 승인자에게 문서 위치와 미발송 사실을 전달합니다. 최종 답변도 “초안 저장 완료, 발송은 검토 대기”로 범위를 구분해야 합니다.

메일 차단을 단순 네트워크 오류로 보고 자동 재시도하거나 승인 규칙을 제거해서는 안 됩니다. 재실행할 때 저장을 또 해야 하는지, 이미 끝난 단계는 어디인지 확인하는 방법은 AI 에이전트 재시도·복구 설계에서 이어집니다.

운영 경보 기준 만들기

한 실행의 단계 수가 내부 상한을 초과함
같은 오류 코드가 연속 발생함
승인 없이 쓰기·삭제·발송 도구가 호출됨
평균 입력 토큰이나 실행 시간이 기준보다 크게 증가함
실패했는데 최종 상태가 성공으로 기록됨
로그에 API 키·비밀번호 형식이 탐지됨

경보는 무조건 차단할 항목과 관찰만 할 항목을 나누세요. 보안·권한 위반은 차단하고, 일시적인 지연 증가는 추세를 확인하는 방식이 가능합니다.

자주 묻는 질문

Q1. 모든 프롬프트와 답변을 저장해야 하나요? 아닙니다. 디버깅 목적과 개인정보 위험을 비교해 요약·해시·식별자를 우선 사용하고 원문은 별도 정책으로 관리하세요.

Q2. 로그와 트레이스는 무엇이 다른가요? 로그는 개별 사건 기록이고 트레이스는 한 실행 안의 여러 호출 관계를 연결해 보여 주는 개념에 가깝습니다.

Q3. 성공한 실행도 보관해야 하나요? 성공 기준선과 비용 변화를 비교하려면 표본이 필요합니다. 보존 기간과 표본 비율은 위험과 운영 목적에 맞게 정하세요.

Q4. 도구 오류가 없는데 답이 틀렸습니다. 완료 조건과 품질 평가를 확인하세요. AI 평가 실전처럼 최종 결과를 별도 질문 세트로 검사해야 합니다.

공식 자료와 확인 기준일

확인 기준일: 2026-08-30