🤗 08. 본편 03: 멀티에이전트 인시던트 커맨더 만들기

이번 편은 **“에이전트 1개로 다 하려다 복잡해지는 문제”**를 해결한다.
핵심은 간단하다: 역할을 나눈 두 전문 에이전트(risk_analyst, response_planner)를 매니저 에이전트가 오케스트레이션하게 만든다.

• 이전 편(실습편 01): 🤗 07. 실습편 01

한 줄 결론

smolagents의 managed_agents 패턴으로 역할을 분리하면, 초보자도 **장애 대응 의사결정(type/severity/lane/comms/eta/rollback)**을 재현 가능하게 자동화할 수 있다.

공식 근거 바로보기

• Agents Course 저장소: 코스 전체 구조/단원 안내
  https://github.com/huggingface/agents-course
• Agents Course Unit 2 smolagents: Multi-Agent Systems 포함
  https://huggingface.co/learn/agents-course/unit2/smolagents/introduction
• smolagents docs: CodeAgent/ToolCallingAgent/managed_agents 개념
  https://huggingface.co/docs/smolagents

왜 멀티에이전트가 실무에서 유리한가

smolagents 튜토리얼의 베스트 프랙티스처럼, 좋은 시스템은 “복잡한 판단을 작고 명확한 역할”로 쪼갤수록 안정적이다.

• risk_analyst: 장애 타입/심각도/ETA 산정
• response_planner: 대응 lane/커뮤니케이션/롤백 정책 추천
• manager: 두 결과를 합쳐 최종 의사결정 포맷으로 정리

flowchart LR
  A[장애 입력: issue/users/payment] --> B[manager agent]
  B --> C[risk_analyst]
  C --> D[type/severity/eta]
  B --> E[response_planner]
  D --> E
  E --> F[lane/comms/rollback]
  F --> G[FINAL: 운영결정 6필드]

쉬운 비유

• 한 명에게 “진단+대응+보고”를 모두 맡기면 실수가 늘어난다.
• 병원처럼 진단팀과 처치팀을 나누고, 마지막에 당직 총괄이 확정하면 운영 품질이 올라간다.

---

실습: 25~35분 재현 (도구/입력/실행명령/성공판정)

실습 파일 경로:
/home/tw2/Documents/n8n/data/shared/syn/8.quartz/Agent/🤗 HF-Agents-Course/downloads

Step 1) 환경 준비

• 도구: Python 3.10+, 터미널
• 입력: requirements.txt
• 실행명령:

cd /home/tw2/Documents/n8n/data/shared/syn/8.quartz/Agent/🤗\ HF-Agents-Course/downloads
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

• 성공판정: 설치 에러 없이 종료, (.venv) 표시

Step 2) 도구 셀프체크 (모델 호출 전)

• 도구: day8_multiagent_incident_commander.py
• 입력: 내장 규칙 테스트(incident type/severity/lane/comms/rollback)
• 실행명령:

python day8_multiagent_incident_commander.py --mode selfcheck

• 성공판정: 출력 JSON에 "tools_ok": true

Step 3) 단일 장애 요청 실행

• 도구: day8_multiagent_incident_commander.py
• 입력:
  • issue: 결제 승인 실패가 급증하고 고객 불만이 접수됩니다.
  • users: 3200
  • payment: 1
• 실행명령:

# .env에 OPENAI_API_KEY 또는 HF_TOKEN 필요
python day8_multiagent_incident_commander.py \
  --mode single \
  --provider auto \
  --issue "결제 승인 실패가 급증하고 고객 불만이 접수됩니다." \
  --users 3200 \
  --payment 1

• 성공판정:
  • parsed.parse_ok = true
  • parsed.severity = "sev1"에 근접
  • parsed.lane = "WAR_ROOM"에 근접

Step 4) 배치 평가 (재현성 확인)

• 도구: day8_multiagent_incident_commander.py, sample_tasks_day8.json
• 입력: 장애 시나리오 3건 + 기대값
• 실행명령:

python day8_multiagent_incident_commander.py \
  --mode eval \
  --provider auto \
  --input sample_tasks_day8.json

• 성공판정:
  • "pass": true 또는
  • "score" >= 0.66

---

실무 적용 포인트

1. SRE/온콜 운영: sev1/sev2/sev3 기준을 함수로 고정해 개인차 줄이기
2. 커뮤니케이션 표준화: status page 공개 기준을 choose_comms_channel로 규칙화
3. 릴리즈/롤백 안전장치: 결제 경로 영향(payment_path)을 롤백 정책과 직접 연결

현장형 미니 사례

사례 A) 장애 심각도 분류가 사람마다 달랐던 팀

assess_severity 규칙을 코드로 고정한 뒤, 장애 회의에서 “왜 sev1인지”를 함수 로직으로 즉시 설명할 수 있게 됐다.

사례 B) 공지 채널이 늦어지는 문제

choose_comms_channel에 사용자 영향 수 기준을 넣어, 대규모 장애에서 status page 공지가 자동으로 우선되도록 바꿨다.

자주 막히는 4가지

1. 모델 키를 찾지 못했습니다
   • .env에 OPENAI_API_KEY 또는 HF_TOKEN 설정 필요
2. parse_ok = false
   • FINAL: 출력 계약을 프롬프트에서 임의 변경했는지 확인
3. 경로 공백/이모지 오류
   • 🤗 HF-Agents-Course 경로를 따옴표 또는 \ 로 이스케이프
4. eval 점수 낮음
   • sample_tasks_day8.json에 실제 팀 장애 케이스를 추가해 규칙 보정

적용 체크리스트

• selfcheck 성공 (tools_ok=true)
• single에서 parse_ok=true 확인
• eval 점수 기록 (score)
• 우리 팀 기준으로 severity/comms/rollback 규칙 1개 이상 수정

참고 링크 (우선순위)

1. https://github.com/huggingface/agents-course
2. https://huggingface.co/learn/agents-course
3. https://huggingface.co/docs/smolagents

실습 파일 다운로드

• Day8 실습 가이드 README
• day8_multiagent_incident_commander.py
• sample_tasks_day8.json
• hf-agents-day8-multiagent-incident-commander.zip

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 작성과 구조화를 수행했으며, 최종 발행 전 사람이 사실관계와 재현 절차를 검토했다.