대부분의 멀티 에이전트 시스템을 구축하는 팀은 가장 먼저 옵저버빌리티 툴링을 찾는다. 대시보드를 연결하고, 알림 임계값을 설정하고, 로그 애그리게이터를 구성한다. 그런 다음 배포한다. 그러면 무언가 조용히 깨지고, 어떤 에이전트가 원인인지, 그것이 무엇을 해야 했는지, 누가 수정 책임자인지 아무도 알 수 없다.
빠진 단계는 더 나은 모니터링이 아니다. 플릿 인벤토리다.
플릿 인벤토리란 무엇인가
플릿 인벤토리는 시스템에서 실행 중인 모든 에이전트의 머신 리더블 레코드다. README가 아니다. Notion 문서도 아니다. 인프라가 읽고, 검증하고, 쿼리할 수 있는 구조화된 파일 — JSON, YAML, TOML, 원하는 형식으로 — 이다.
각 항목은 세 가지 질문에 답한다:
- 이 에이전트는 무엇인가?
- 정상 상태를 어떻게 확인하는가?
- 정상이 아닐 때 무슨 일이 일어나는가?
그 레코드 없이는 모니터링 툴이 이해하지 못하는 시스템을 감시하는 것이다. 프로세스가 다운됐다는 것은 알 수 있다. 하지만 그 프로세스가 실행되어야 했는지, 무엇을 담당했는지, 어떤 다운스트림 에이전트가 이제 입력을 받지 못하는지는 알 수 없다.
모든 항목에 반드시 포함해야 할 세 가지 필드
1. 식별 정보 (Identity)
식별 정보는 이름 이상이다. 유용한 identity 블록에는 다음이 포함된다:
- 캐노니컬 이름 — 로그, 알림, 핸드오프에서 사용되는 정확한 문자열
- 역할 — 에이전트의 기능과 파이프라인 내 위치를 설명하는 한 문장
- 소유자 — 동작에 책임지는 팀 또는 개인
- 버전 — 배포된 버전, 레포의 최신 태그가 아닌
캐노니컬 이름은 생각보다 중요하다. 로그 애그리게이터는 prospect-enricher라고 부르고, 알림은 enrichment-agent로 발생하고, 런북은 lead-enrichment-worker를 참조한다면, 하나의 대상에 세 가지 이름이 생긴다. 새벽 2시 인시던트 중에 그 모호함은 20분을 낭비하게 만든다.
2. 헬스비트 계약 (Heartbeat Contract)
헬스비트 계약은 정상 상태가 측정 가능한 용어로 어떤 모습인지 정의한다:
- 예상 주기 — 에이전트가 출력을 생성해야 하는 빈도 (예: 90초마다 최소 하나의 레코드 처리)
- 레이턴시 상한 — 입력 수신과 출력 방출 사이의 최대 허용 시간
- 에러율 임계값 — 알림을 트리거하는 실패 비율 대 일반 노이즈
이 수치는 추측이 아니라 스테이징에서 관찰된 동작에서 나와야 한다. 현실적인 부하로 48시간 동안 에이전트를 실행하라. p95 레이턴시를 기록하라. 그 수치의 2배로 상한을 설정하라. 이제 모니터는 막연한 "느린 것 같다"는 느낌이 아니라 계약을 집행하게 된다.
3. 장애 에스컬레이션 경로 (Failure Escalation Path)
이 필드는 다음 질문에 답한다: 헬스비트 계약이 위반되면 다음에 무슨 일이 일어나는가?
최소한의 에스컬레이션 경로는 세 단계로 구성된다:
- 자동 재시도 정책 — 에이전트가 실패로 간주되기 전까지 몇 번 재시도하고, 어떤 백오프를 사용하는가
- 폴백 동작 — 파이프라인이 일시 중지되는가, 실패한 에이전트를 우회하는가, 아니면 저하된 출력을 방출하는가?
- 인간 에스컬레이션 대상 — 어떤 사람 또는 채널이 알림을 받고, 조치를 취하는 데 필요한 정보는 무엇인가
폴백 동작은 대부분의 팀이 건너뛰는 필드다. 알림은 정의하지만 응답은 정의하지 않는다. 그래서 알림이 발생하면 온콜 엔지니어는 문서화된 지침 없이 압박 속에서 판단을 내려야 한다. 시스템이 안정적일 때 폴백 동작을 작성하라, 깨진 후가 아니라.
첫 번째 인시던트 전에 부트스트랩하는 방법
첫날부터 완벽한 인벤토리가 필요한 것은 아니다. 완전한 인벤토리가 필요하다 — 일부 필드가 플레이스홀더라도 모든 에이전트가 포함된.
실용적인 부트스트랩 순서:
- 현재 프로덕션에서 실행 중인 모든 에이전트를 나열하라. 5분 안에 기억으로 나열할 수 없다면, 그것이 첫 번째로 해결해야 할 문제다.
- 환경별로 하나의 인벤토리 파일을 생성하라 (프로덕션, 스테이징). 인프라 코드와 함께 버전 관리에 보관하라.
- 먼저 identity 필드를 채워라. 캐노니컬 이름, 역할, 소유자, 버전. 대부분의 시스템에서 한 시간도 걸리지 않는다.
- 관찰된 데이터로 헬스비트 계약을 계측하라. 스테이징에 배포하고, 48시간 동안 현실적인 트래픽을 실행하고, 수치를 기록하라.
- 다음 기능을 작성하기 전에 장애 에스컬레이션 경로를 작성하라. 이것을 백로그 항목이 아닌 블로킹 태스크로 취급하라.
DK1.AI에서는 첫 번째 에이전트가 라이브되기 전에 이 인벤토리로 모든 프로덕션 시스템 구축을 시작한다. AI Brand Presence 배포를 구축할 때, 플릿 인벤토리는 우리가 마지막이 아닌 가장 먼저 생산하는 아티팩트다. 모니터링 구조화 방식, 완료 정의 방식, 클라이언트 팀에 운영을 인계하는 방식을 결정한다.
인벤토리는 장애를 방지하지 않는다. 장애를 읽기 쉽게 만든다. 읽기 쉬운 장애는 진단하는 데 15분이 걸린다. 읽기 어려운 장애는 3시간과 워룸이 필요하다.
실질적인 이점
인벤토리 없이 8개의 에이전트를 운영하는 팀은 인시던트당 무엇이 깨졌고 왜 그런지 파악하는 데만 약 23시간을 소비한다. 최신 인벤토리를 갖춘 동일한 팀은 그것을 30분 이내로 단축한다. 4번의 인시던트가 있는 분기 동안, 그것은 610시간 회복 — 게다가 엔지니어가 수정하는 시스템을 신뢰하기 때문에 더 빠른 이터레이션의 복리 효과까지.
단순한 것이 이긴다. 레포에 체크인된 YAML 파일이 매핑되지 않은 시스템 위에 구축된 아름다운 옵저버빌리티 대시보드를 이긴다.