RunbookHermes: Hermes Agent 기반의 증거 중심 AIOps 인시던트 대응 에이전트

9bow · 5월 7, 2026, 9:30오후

RunbookHermes 소개

운영 환경에서 결제 시스템 장애 같은 인시던트(Incident)가 발생하면, 메트릭(Metrics)·로그(Logs)·트레이스(Traces)·배포 이력 같은 증거를 모으고, 가설을 세우고, 위험한 조치는 승인을 받아 점검(Checkpoint) 후 실행하며, 복구 검증과 사후 회고까지 마쳐야 합니다. 단순히 챗봇 형태의 에이전트(Agent)가 답을 내놓는 것만으로는 운영 책임 영역을 다루기에 부족합니다. RunbookHermes는 NousResearch의 Hermes Agent 런타임을 바탕으로, 이러한 인시던트 대응 워크플로우를 도메인 레이어로 얹은 오픈소스 AIOps 에이전트입니다.

이 프로젝트의 설계 의도는 명확합니다. Hermes Agent의 런타임 루프, 프로바이더 라우팅(Provider Routing), 도구 시스템, 메모리 프로바이더, 컨텍스트 엔진(Context Engine), 스킬 시스템, 게이트웨이 구조, 안전 경계(Safety Boundary)를 그대로 계승한 위에, AIOps에 필요한 인시던트 정의·증거 수집·승인 게이트·롤백·복구 검증·런북 학습 같은 기능을 별도의 플러그인 계층으로 추가하는 방식입니다. 결과적으로 별도의 데모 대시보드가 아니라, Hermes Agent의 강점을 그대로 살린 운영 가능한 수준의 AIOps 시스템을 목표로 합니다.

또한 RunbookHermes는 모델이 환각(Hallucination)으로 답을 메우는 것을 막기 위해 결정론적 증거(Deterministic Evidence)와 모델 보조 분석(Model-Assisted Analysis)을 분리합니다. 증거 수집과 안전 게이트는 결정론적으로 동작하고, 모델은 운영자에게 보여 줄 인시던트 요약·근본 원인 설명·운영자용 액션 요약 같이 가독성을 높이는 부분에 한정해 사용됩니다. 모델 프로바이더가 설정되어 있지 않으면 모델 보조 요약은 비활성화되며, 핵심 워크플로우는 모델 없이도 동작합니다.

RunbookHermes의 시스템 구성

RunbookHermes 콘솔은 인시던트 컨트롤 플레인(Control Plane), 실시간 모니터링, 인시던트 상세, 증거 카드, 액션과 승인, 타임라인, 생성된 런북 스킬 등을 한 화면에서 다룹니다. 다음 스크린샷은 콘솔의 개요 페이지로, 인시던트 카운트, 보류 중인 승인, 생성된 스킬, 핵심 서비스, 권장 운영 흐름, 현재 능력 경계를 함께 보여 줍니다.

증거 중심의 인시던트 상세 페이지에서는 메트릭·로그·트레이스 기반 증거 카드와 함께, 근본 원인·권장 조치·증거 ID·신뢰도(Confidence)·승인 상태가 정리된 임원용 요약(Executive Summary)이 한꺼번에 노출됩니다. 모델 보조 요약은 결정론적 증거와 시각적으로 분리되어 표시되어, 운영자가 어디까지가 사실 기반이고 어디부터가 모델 해석인지를 명확히 구분할 수 있도록 설계되어 있습니다.

리스크가 있는 액션은 단일 버튼 클릭으로 즉시 실행되지 않습니다. RunbookHermes는 액션 정책 검사, 승인 요청, 체크포인트 생성, 드라이런(Dry-Run), 통제된 실행(Controlled Execution), 복구 검증(Recovery Verification), 감사 타임라인이라는 7단계의 안전 게이트를 통과해야만 실제로 환경을 변경합니다. 이 흐름이 인시던트 타임라인에 모두 기록되어 사후 감사에 활용됩니다.

타임라인 탭에는 인시던트 생성, 증거 수집, 가설 생성, 액션 계획, 체크포인트 생성, 승인 요청과 결정, 스킬 생성, 실행 결과까지 인시던트 라이프사이클의 전 단계가 시간 순으로 기록됩니다. 회고와 자동화 가능 영역의 식별이 이 타임라인을 출발점으로 삼을 수 있도록 설계되어 있습니다.

RunbookHermes가 Hermes Agent로부터 계승하는 능력

RunbookHermes는 처음부터 단순 룰 엔진으로 새로 짜는 대신, Hermes Agent의 아키텍처를 인시던트 대응 도메인에 맞게 적응시킵니다. 다음 표는 Hermes Agent의 각 능력이 RunbookHermes에서 어떻게 확장·재사용되는지를 보여 줍니다.

Hermes Agent 능력	RunbookHermes 적응
Agent runtime / loop	`runbook-hermes` 프로파일의 코어 에이전트 기반으로 그대로 사용
Provider / model routing	모델 프로바이더 유연성을 유지하고, 인시던트 분석용 OpenAI 호환 모델 요약을 추가
Tool system	Prometheus, Loki, Jaeger/Trace, 배포 이력, 승인, 롤백, 복구 검증을 위한 도구 추가
Memory provider	서비스 프로파일·인시던트 요약·팀 선호·스킬 인덱스를 위한 IncidentMemory 추가
Context engine	알림·증거·가설·액션·최종 답변을 압축하는 EvidenceStack 컨텍스트 엔진 추가
Skills	결제 HTTP 503 트리아지, 일반 인시던트 트리아지 같은 런북 스킬 추가
Gateway architecture	Alertmanager, Feishu, WeCom, Web/API 진입 경로를 인시던트 워크플로우용으로 추가
Safety boundary	위험 액션을 위한 승인·체크포인트·드라이런·통제된 실행·복구 검증 추가
Execution backend	로컬 참조 롤백 외에 `custom_http`, Kubernetes, Argo CD 스타일 어댑터 인터페이스 추가

특히 EvidenceStack 컨텍스트 엔진은 인시던트 대응 시 프롬프트가 비대해지는 문제를 다루기 위한 도메인 특화 설계입니다. 메트릭 샘플, 트레이스 페이로드, 도구 출력, 승인 이력, 타임라인 같은 원시 컨텍스트를 모두 모델 프롬프트에 던지는 대신, 알림 요약·핵심 증거·가설·액션 계획·최종 답변이라는 다섯 영역으로 정리하고, 큰 페이로드는 증거 ID와 요약만 컨텍스트에 남겨 추론 비용과 환각 가능성을 함께 낮춥니다.

IncidentMemory는 단순한 채팅 이력 저장이 아니라, 시간이 지나도 의미 있는 운영 지식만 골라 기억하도록 설계되어 있습니다. 서비스 프로파일, 팀 선호, 인시던트 요약, 반복되는 근본 원인, 생성된 런북 스킬, 위험 액션의 승인 요건이 그 대상이며, 다음 인시던트가 발생했을 때 적절한 운영 사실을 적시에 회상하는 것이 목표입니다.

RunbookHermes 배포와 사용 예시

RunbookHermes는 단일 코드베이스로 배포됩니다. 공식 Hermes Agent를 별도로 띄운 다음 그 옆에 추가 앱을 붙이는 구조가 아니라, Hermes Agent 상위 소스와 RunbookHermes AIOps 확장 레이어가 함께 들어 있는 단일 저장소를 클론하여 필요한 진입점을 실행하는 방식입니다. 가장 가벼운 모드는 Web/API만 띄워 콘솔과 API 표면을 점검하는 것입니다.

set PYTHONPATH=.
python -m uvicorn apps.runbook_api.app.main:app \
  --host 127.0.0.1 --port 8000

# 콘솔 페이지
# http://127.0.0.1:8000/web/index.html
# http://127.0.0.1:8000/web/monitoring.html
# http://127.0.0.1:8000/web/incidents.html
# http://127.0.0.1:8000/web/approvals.html

전체 인시던트 대응 경로를 실제 관측 스택과 함께 검증하려면, 결제 시스템과 Prometheus·Loki·Jaeger·Grafana 등을 한꺼번에 띄우는 로컬 참조 환경을 사용할 수 있습니다. demo/payment_system/docker compose up --build 후 다음 환경 변수를 설정하면 RunbookHermes가 실제 어댑터를 사용하도록 전환됩니다.

set OBS_BACKEND=real
set DEPLOY_BACKEND=demo_file
set TRACE_BACKEND=jaeger
set TRACE_PROVIDER_KIND=jaeger
set ROLLBACK_BACKEND_KIND=demo_file
set RUNBOOK_CONTROLLED_EXECUTION_ENABLED=true

set PROMETHEUS_BASE_URL=http://127.0.0.1:9090
set LOKI_BASE_URL=http://127.0.0.1:3100
set TRACE_BASE_URL=http://127.0.0.1:16686

장애 시나리오는 결제 503, 쿠폰 504 타임아웃, 주문 429 레이트 리밋 같은 케이스가 사전 정의되어 있고, scripts/generate_traffic.py --fault PAYMENT_503_AFTER_DEPLOY --requests 60 처럼 의도된 부하를 흘려보내며 전체 흐름을 끝까지 검증할 수 있습니다. 이 시나리오들은 최종 목표가 아니라, 실제 시스템과 어떻게 연결되는지를 증명하기 위한 로컬 참조 환경이라는 점이 README에 명시되어 있습니다.

RunbookHermes 라이선스

RunbookHermes 프로젝트는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용·수정·재배포할 수 있습니다. 다만 운영 환경에 도입할 때는 결정론적 증거 어댑터(Prometheus, Loki, Jaeger 등)와 안전 게이트의 정책을 조직 표준에 맞게 점검한 뒤 사용하는 것이 권장됩니다.

RunbookHermes 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~