몇 분 만에 완성하는 런북(Runbooks): HazelJS를 활용한 온콜(On-call) 장애 대응 코파일럿(Copilot)

운영 환경(Production)에 문제가 발생했을 때, 엔지니어들은 일반적인 챗봇이 아니라 로그, 메트릭, 그리고 **런북(Runbooks)**을 찾습니다. 유용한 장애 대응 코파일럿(Incident copilot)은 페이징 시스템(Paging system)을 대체하려 들지 않으면서도, **영향도를 분류(Classifies impact)**하고, 적절한 플레이북(Playbook)을 제시하며, **고객에게 안전한 언어로 초안을 작성(Drafts customer-safe language)**합니다.

핵심 아이디어는 트리아지(Triage, 우선순위 분류) 사실과 커뮤니케이션 톤(Comms tone)을 분리하는 것입니다. 즉, 두 개의 에이전트(Agent)와 하나의 슈퍼바이저(Supervisor)를 사용하고, 먼저 피스처(Fixtures)를 적용한 뒤 실제 데이터 소스로 교체하는 방식입니다.

우리가 구축하는 것

• 심각도 트리아지(Severity triage) — 구조화된 도구 출력 (컴포넌트, 고객 영향도, 제안된 심각도).
• 런북 검색(Runbook retrieval) — 온콜(On-call) 플레이북에 대한 키워드 검색 (피스처 → 이후 Confluence / Notion).
• 고객 업데이트 초안 작성(Customer update drafting) — 신중한 언어를 사용한 짧은 상태 메시지.
• 슈퍼바이저 라우팅(Supervisor routing) — createSupervisor가 여러 라운드에 걸쳐 트리아지(Triage) vs 런북(Runbook) vs 커뮤니케이션(Comms)을 선택.

providers에 **IncidentController**와 세 개의 @Agent 클래스를 추가하고, AgentModule 이전에 파일을 임포트(Import)한 뒤, POST /incident/analyze(단일 코디네이터)와 POST /incident/supervisor(멀티 워커 라우터)를 노출합니다.

런타임 전제 조건(Runtime prerequisites): 동일한 AI 네이티브 베이스라인 — 템플릿 부팅을 위한 Postgres, npm run db:push, OPENAI_API_KEY, npm run dev.

피스처 런북(Fixture runbooks)

const RUNBOOKS = [
  {
    id: 'rb-payment-latency',
...

에이전트(Agents)

트리아지 에이전트(Triage agent)

@Agent({
  name: 'IncidentTriageAgent',
  description: 'Classifies incidents and suggests immediate checks',
...

런북 검색 에이전트(Runbook search agent)

@Agent({
  name: 'RunbookSearchAgent',
  description: 'Finds runbook steps for a symptom',
...

고객 커뮤니케이션 에이전트(Customer comms agent)

@Agent({
  name: 'CustomerCommsAgent',
  description: 'Drafts cautious external status updates',
...

HTTP 컨트롤러 (supervisor)

@Controller('incident')
export class IncidentController {
  constructor(private readonly agentService: AgentService) {}
...

실행 및 테스트(Running & testing)

실행 및 테스트(Running & testing)

npx @hazeljs/cli g app incident-copilot-demo --template=ai-native
cd incident-copilot-demo
cp .env.example .env
...

1) Triage 전용(Triage-only) — triage.json:

{ "message": "Checkout is slow; customers see 8s latency on payment confirm in EU." }

curl.exe -s -X POST http://localhost:3000/incident/triage 
-H "Content-Type: application/json" 
-d "@triage.json"

2) 감독관(Supervisor) — incident.json:

{
  "message": "Kafka lag spiked on ingestion-raw; pipeline stalled. Draft a cautious customer update and cite runbook steps."
}

curl.exe -s -X POST http://localhost:3000/incident/supervisor 
-H "Content-Type: application/json" 
-d "@incident.json"

3) 검사기(Inspector) — 경로 및 모듈 내부 검사를 위해 http://localhost:3000/__hazel을 사용합니다.

**CustomerCommsAgent**를 VPN 외부로 노출하기 전에 **GuardrailsModule**과 함께 사용하세요.

프로덕션 배포 전 변경할 사항(What to change before production)

• **searchRunbooks**를 실제 지식 기반(KB)에 연결하고, 검색된 모든 단계에 **버전 ID(version ids)**를 유지하세요.
• 공개 초안에 대한 **승인(approval)**을 추가하세요 (requiresApproval: true를 게시 도구에 적용).
• 감사를 위해 PagerDuty / Jira 인시던트에 **실행 ID(execution ids)**를 첨부하세요.
• 잦은 오탐지 경보로 인한 남용을 방지하기 위해 /incident/*에 **속도 제한(rate limits)**을 추가하세요.

HazelJS는 두 번째 오케스트레이션 제품 없이 네이티브 멀티 에이전트 라우팅(native multi-agent routing) 기능을 제공합니다. 전문가는 작게 유지되고, **createSupervisor**가 대시보드용 **라운드 메타데이터(round metadata)**를 노출하며, 동일한 모듈 스택은 RAG 및 Flow 기반 플레이북까지 확장됩니다.

패키지 링크 (Package links)

• @hazeljs/cli
• @hazeljs/core
• @hazeljs/agent
• @hazeljs/guardrails
• @hazeljs/flow
• HazelJS GitHub

HazelJS 사이트 (HazelJS site)

• 공식 웹사이트(Oficcial Site)
• 문서(Documentation)