고통스러운 상황: 당신의 에이전트가 새벽 3시에 죽었습니다. 알림도, 로그도, 아무도 몰랐습니다. 단 하나의 API 호출 내부에서 조용히 실패했고, 에러는 재시도 루프(retry loop)에 의해 삼켜졌습니다. 다음 날 아침 대시보드를 열었을 때 나타난 문구는 — "도구 응답 없음(Tool not responding)."
배울 내용: AI 에이전트를 위한 전체 운영(Ops) 스택 — 3계층 상태 체크(health checks), P0–P3 알림 레벨, 인시던트 런북(incident runbooks), 토큰 및 비용 거버넌스(governance), 그리고 단일 서버에서 실행할 수 있는 원클릭 Prometheus + Grafana 배포 방법.

0. 사전 요구 사항 (Prerequisites)

1. 왜 에이전트에 운영(Ops)이 필요한가 — 조용히 죽고 아무도 모른다

실제 인시던트(incident) 사례로 시작하겠습니다.

저의 에이전트 "Yuanbao"는 데이터 수집 작업을 수행했습니다. 매일 새벽 2시에 91개 대학의 입학 데이터를 스크래핑하고, 정제하고, 비교하여 보고서를 생성하는 작업이었습니다. 첫 주에는 아무 문제 없이 진행되었습니다. 하지만 둘째 주부터 제가 받는 모든 보고서에서 3~5개 대학의 데이터가 누락되기 시작했습니다.

조사 과정은 고통스러웠습니다:

• 코드 로직 확인 — 정상
• API 제한(limits) 확인 — 정상
• 네트워크 연결성 확인 — 안정적

에이전트의 전체 실행 로그(execution log)를 모두 살펴보고 나서야 진실이 드러났습니다. 37번 대학교가 웹사이트의 API 형식을 변경한 것이었습니다. 에이전트는 응답을 파싱(parse)하는 데 실패했고, 무한 재시도 루프(infinite retry loop)에 빠졌습니다. 8번째 재시도에서 토큰 예산 소진 정책(token-budget exhaustion policy)이 트리거되었지만, 저는 "예산 소진 시" 설정을 **조용히 건너뛰기(silently skip)**로 구성해 두었습니다. 결과적으로 에이전트는 남은 모든 대학교를 조용히 건너뛰고 "보고서 생성" 단계로 넘어갔으며, 겉보기에는 완벽해 보이지만 실제로는 3개의 대학교가 누락된 보고서를 만들어냈습니다.

여기에는 몇 가지 치명적인 문제들이 있었습니다:

그리고 이것은 일회성 사건이 아닙니다. 에이전트 시스템이 3개 이상의 독립적인 작업(independent tasks)을 넘어 성장하게 되면, "어딘가에 문제가 있다"는 상황은 예외가 아닌 일상이 됩니다. 만약 여러분의 운영 태세(ops posture)가 여전히 "몇 시간마다 한 번씩 확인해보자" 수준이라면, 여러분은 반드시 어느 늦은 밤이나 새벽에 사용자로부터 질문을 받게 될 것입니다. 혹은 더 최악의 경우, 사용자는 아무도 눈치채지 못하지만 API 청구 금액이 조용히 3배로 불어나 있을 수도 있습니다.

이것이 바로 우리가 에이전트에 완전한 운영 모니터링(ops monitoring)을 적용하는 이유입니다. 심심해서 하는 것이 아닙니다. 결국 언젠가는 반드시 해야만 하기 때문입니다. 선제적으로(proactively) 대응하면 고통을 관리할 수 있지만, 사후 대응적으로(reactively) 대응하면 피해를 막을 수 없습니다.

2. 상태 체크(Health Checks) — 세 가지 계층: 포트 / API / 비즈니스 로직

운영(ops)에서 가장 중요한 단 한 가지는 현재 시스템이 살아있는지(alive)를 아는 것입니다.

전통적인 DevOps에서 상태 체크(health checks)는 표준입니다. Nginx에는 /health 엔드포인트가 있고, PostgreSQL에는 pg_isready가 있으며, Kubernetes에는 Liveness 및 Readiness 프로브(probes)가 있습니다. 하지만 대부분의 AI 에이전트 프로젝트는 이 계층을 완전히 건너뜁니다.

그들은 "에이전트는 웹 서비스가 아니므로 상태 체크가 필요 없다"라고 생각합니다. 그것은 완전히 틀린 생각입니다.

에이전트 또한 하나의 서비스입니다. 단지 그 "인터페이스(interfaces)"가 HTTP가 아닐 뿐입니다. 에이전트의 인터페이스는 도구 호출 체인(tool-call chains), LLM 응답 품질, 그리고 상태 머신(state-machine) 전환의 정확성입니다. 이 중 어느 것도 체크할 수 없다면, 여러분은 눈을 가리고 비행하는 것과 같습니다.

저는 에이전트 상태 체크(health checks)를 세 가지 계층으로 나누었으며, 각 계층은 서로 다른 형태의 장애를 포착합니다.

계층 1: 포트 및 인프라 상태 (Liveness)

이것은 가장 근본적인 체크입니다. 여러분의 에이전트 코드가 아무리 우아하더라도, 그 아래의 인프라가 죽는다면 모든 것이 무의미해집니다.

구현:

#!/bin/bash
# layer1_liveness.sh — 인프라 생존 여부 체크

...

핵심 원칙: 계층 1 체크는 반드시 에이전트 코드
_외부_에서 독립적으로 실행되어야 합니다. 만약 에이전트 프로세스가 자신의 포트를 직접 체크한다면 — 프로세스가 죽을 때 체크 기능도 함께 죽게 됩니다. cron, systemd 타이머, 또는 별도의 외부 모니터링 서비스를 사용하세요.

계층 2: API 및 의존성 상태 (Readiness)

이 계층은 에이전트가 의존하는 외부 서비스와 API에 접속 가능한지, 그리고 예상된 값을 반환하는지를 체크합니다. 이는 에이전트 운영(agent ops)에서 가장 간과하기 쉬운 사각지대입니다.

에이전트는 전통적인 웹 서비스와 다릅니다. 에이전트의 의존성은 단순히 데이터베이스에 국한되지 않습니다. 다음과 같은 것들이 포함됩니다:

• LLM API (OpenAI / Claude / 로컬 모델)
• 검색 엔진 API
• 제3자 데이터 소스 API
• 내부 도구에 의해 호출되는 마이크로서비스 (Microservices)
• 파일 저장 시스템

만약 어떤 의존성이라도 깨진다면, 에이전트는 "겉보기에는 정상이나 실제로는 쓸모없는" 상태로 동작하게 됩니다.

체크 전략:

#!/usr/bin/env python3
# layer2_readiness.py — API 및 의존성 상태 체크

...

실무적 조언: 계층 2 체크를 30초마다 실행하세요. LLM API의 가용성은 변동성이 매우 큽니다. 장애(또는 스로틀링(throttling))를 일찍 감지할수록, 더 빨리 폴백 모델(fallback model)이나 기능 저하 전략(degradation strategy)으로 전환할 수 있습니다.

계층 3: 비즈니스 로직 및 데이터 품질 상태 (Deep Health)

이 계층은 에이전트만의 고유한 영역이며, 전통적인 웹 서비스에는 없는 차원입니다. 이는 에이전트가 단순히 "살아있는지(alive)"를 넘어, "올바르게(correctly)" 작동하고 있는지를 체크합니다.

구현: 상태 머신 (state-machine)의 모든 전환 시마다, 에이전트는 상태 지표 저장소 (Prometheus / InfluxDB / 또는 단순한 JSON 파일)에 기록을 작성합니다. 별도의 딥 헬스 체크 (Deep Health Check) 프로세스가 주기적으로 해당 지표를 쿼리하여 상태 점수 (health score)를 계산합니다.

#!/usr/bin/env python3
# layer3_deep_health.py — 비즈니스 상태 점수 산정

...

핵심 통찰 (Core insight): 레이어 3 (Layer 3)는 에이전트 운영 (agent ops)을 전통적인 운영 (traditional ops)과 근본적으로 다르게 만드는 요소입니다. 전통적인 운영은 "서비스에 접속 가능한가?"를 묻습니다. 에이전트 운영은 "작업이 올바르게 수행되고 있는가?"도 반드시 물어야 합니다. 그리고 후자가 대개 진짜 재앙입니다. 왜냐하면 에이전트는 정상적으로 잘못된 일을 수행할 수 있기 때문입니다.

3. 알림 레벨 (Alert Levels) — P0 치명적 (Fatal) / P1 심각 (Critical) / P2 경고 (Warning) / P3 통지 (Notice)

상태 체크 (Health checks)는 _탐지 (detection)_에 관한 것입니다. 알림 (Alerts)은 _누군가 알게 하는 것_에 관한 것입니다. 최악의 알림 시스템은 무엇일까요? 모든 문제를 동일하게 취급하는 것입니다.

"데이터베이스 디스크가 거의 가득 참"과 "일부 레시피 웹사이트가 503 에러를 반환함"이 동일한 알림 채널로 들어온다면, 팀은 알림 피로 (alert fatigue)에 빠져 허우적거리거나, 무언가 정말로 망가질 때까지 모든 것을 무시하게 됩니다.

전통적인 SRE 심각도 모델을 에이전트 운영에 적용하여, 제가 사용하는 계층 구조는 다음과 같습니다:

P0 — 치명적 (Fatal) (즉시 대응, 현재 작업 중단)

정의: 핵심 기능이 완전히 사용할 수 없거나, 실제 손실이 발생하고 있는 상태 (자금 소진, 데이터 손실).

전형적인 시나리오:

• 에이전트 프로세스가 완전히 종료되었고, systemd 재시작에 실패함
• 핵심 LLM API를 5분 이상 연속으로 사용할 수 없음 (fallback 모델 없음)
• 데이터베이스 쓰기 실패 → 상태를 유지(persist)할 수 없음
• 현재 시간당 API 지출이 일일 예산의 30%를 초과함
• 무한 루프로 인해 토큰 소비량이 기준치의 10배에 달함

대응: 즉각적인 조치, 인간의 개입이 필요함. 밤중이라 할지라도 예외 없음.
채널: 전화 / Feishu-DingTalk 음성 통화 / SMS

P1 — Critical (30분 이내 대응)

정의: 부분적 손상 — 핵심 경로(core path)는 여전히 작동 중이지만, 조치하지 않을 경우 1시간 이내에 P0로 격상될 상황.

전형적인 시나리오:

• 단일 외부 API 의존성 다운 (Fallback(대체 수단)이 존재하지만 자동 전환되지 않음)
• 상태 머신(State machine) 내에서 작업이 30분 이상 정체됨
• 상태 체크(Health checks)가 3회 연속 실패
• 디스크 사용률 85% 초과
• 토큰 소비량이 기준치의 3배 도달

대응: 30분 이내에 확인(acknowledge), 2시간 이내에 수정 또는 기능 저하(degrade) 조치.
채널: @mention이 포함된 Feishu/DingTalk 메시지 + 오디오/비디오 통화 (전화 제외)

P2 — Warning (4시간 이내 대응)

정의: 시스템은 정상 작동 중이나, 잠재적 위험 또는 경미한 이상 징후가 존재함.

전형적인 시나리오:

• 단일 상태 체크가 간헐적으로 실패 (1시간 이내에 자가 복구됨)
• 데이터 품질 탐지 결과 이상치(outlier) 비율이 임계값을 초과함
• 작업 큐(Task queue)에 백로그가 쌓였으나 여전히 처리 중임
• 메모리 사용률 70% 초과
• SSL 인증서 만료가 7일 이내로 다가옴

대응: 다음 영업일 이내에 처리.
채널: Feishu/DingTalk 일반 메시지 + 대시보드 마커

P3 — Notice (관찰하되 조치하지 않음)

정의: 정보 제공용 — 즉각적인 조치는 필요 없으나, 기록하고 관찰할 가치가 있음.

전형적인 시나리오:

• 일일 에이전트 작업 보고서 (X개 작업 완료)
• 일일 토큰 소비 보고서 (어제보다 많거나 적음)
• 새 버전 배포 성공
• 데이터베이스 백업 완료
• 낮은 우선순위의 로그 패턴 발견

대응: 읽기만 하면 됨.
채널: Feishu/DingTalk 일반 메시지 (@mention 없음)

알람 피로(Alert Fatigue) 방지하기

저의 철칙 하나: 만약 알람이 울렸는데 아무도 조치할 필요가 없다면, 그것은 소음(noise)이다. 소음은 참는 것이 아니라 제거해야 한다.

매달 "알람 감사(alert audit)"를 수행하세요. 지난 30일 동안 발생한 모든 알람을 추출하여, 발생한 모든 알람이 실제로 조치로 이어졌는지 확인하십시오. 만약 어떤 알람이 10번 울렸는데 10번 모두 아무도 대응하지 않았다면, 해당 알람의 우선순위를 낮추거나 오탐률(false-positive rate)을 수정해야 합니다.

4. 인시던트 대응 런북 (Incident Response Runbooks) — 탐지에서 복구까지의 표준화된 경로

알람이 울렸습니다. 이제 무엇을 해야 할까요?

대부분의 팀이 무너지는 지점이 바로 여기입니다. 알람은 울리는데 아무도 무엇을 해야 할지 모르거나, 모두가 각자 행동하여 중복된 혼란이 발생합니다.

런북 (Runbook, 인시던트 대응 플레이북)은 이 문제를 해결합니다. 즉, "공황 상태의 조사"를 "절차에 의해 실행되는 표준화된 운영"으로 바꿔줍니다.

나의 런북 템플릿

# 런북: [인시던트 이름]
버전: v1.0 | 최종 업데이트: 2026-07-01

...

세 가지 실제 에이전트 장애 런북

런북 #1: LLM API 타임아웃 폭풍 (LLM API timeout storm)
시나리오: OpenAI API가 5xx 에러를 반환하거나 반복적으로 타임아웃(>30초)이 발생함. 심각도: P1 (폴백 모델(fallback model)이 있는 경우) → P0 (폴백 모델이 없는 경우).
빠른 복구:

• OpenAI 상태 페이지 확인: https://status.openai.com
• 장애가 확인되면 → 폴백 모델로 전환: agent config set model claude-sonnet-4
• 로컬 장애 캐시(failure cache)가 존재하는 경우 → 기능 저하 모드(degradation mode) 시작 (캐시된 작업만 처리, 새로운 호출은 하지 않음)
  근본 원인:
• API 키가 최근에 한도를 초과했는지 확인
• 배치 재시도(batch retries)가 속도 제한(rate limiting)을 유발했는지 확인
• 과거 로그 확인 — 특정 시간에 반복적으로 발생하는지 확인

런북 #2: 상태 머신 데드락 (State-machine deadlock)
시나리오: 작업이 30분 이상 "실행 중(executing)" 상태로 멈춰 있음. 심각도: P2 (단일 작업) → P1 (3개 이상의 작업이 멈춤).
빠른 복구:

• 작업을 강제로 실패로 표시: agent task force-fail
• 고립된 프로세스(orphaned processes) 확인
• 여러 작업이 동시에 멈춘 경우 → 에이전트 프로세스 재시작
  근본 원인:
• 모든 도구(tool)