🤗 07. 실습편 01: 릴리즈 게이트 미니 프로젝트 핸즈온

이번 편은 Hugging Face Agents Course의 **Hands-on 철학(작게 만들고, 바로 검증하고, 수치로 개선 확인)**을 따라, 배포 승인 전에 자주 쓰는 릴리즈 게이트 의사결정 미니 프로젝트를 만든다.

핵심은 간단하다.

• 에이전트가 변경요청을 읽고
• 리스크를 판단한 뒤
• 테스트 범위/배포 윈도우를 제안하고
• FINAL 형식으로 구조화 결과를 남긴다.

이전 편(본편 02)에서 다룬 ToolCallingAgent 패턴을 그대로 실무성 있게 확장한다.

• 이전 편: 🤗 06. 본편 02

한 줄 결론

ToolCallingAgent + 명시적 도구 체인 + 배치 평가(eval) 조합이면, 초보자도 30분 안에 배포 게이트 자동화의 최소형을 재현할 수 있다.

공식 근거 바로보기

• Agents Course(커리큘럼): https://huggingface.co/learn/agents-course
• Course 저장소(실습 코드): https://github.com/huggingface/agents-course
• smolagents 문서(Agent/Tool 패턴): https://huggingface.co/docs/smolagents

flowchart LR
  A[변경 요청 입력] --> B[detect_change_type]
  B --> C[assess_release_risk]
  C --> D[choose_test_plan]
  D --> E[choose_deploy_window]
  E --> F[FINAL: type/risk/test/window]
  F --> G[배포 승인 회의 체크리스트 반영]

0) 실습 목표

• smolagents의 ToolCallingAgent로 릴리즈 게이트 에이전트를 실행한다.
• selfcheck -> single -> eval 순서로 재현 가능한 실행 루프를 만든다.
• score 기준으로 안정성(재현성)을 확인한다.

---

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) 프롬프트 표시
  • 패키지 설치 에러 없이 종료

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

• 도구: day7_release_gate_handson.py
• 입력: 내장 체크 케이스(변경유형/리스크/테스트/배포윈도우)
• 실행명령:

python day7_release_gate_handson.py --mode selfcheck

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

3) 단일 요청 실행 (핸즈온)

• 도구: day7_release_gate_handson.py
• 입력:
  • change: 결제 API 장애 긴급 hotfix 배포가 필요합니다.
  • users: 1200
  • payment: 1
• 실행명령:

# .env에 OPENAI_API_KEY 또는 HF_TOKEN 필요
python day7_release_gate_handson.py \
  --mode single \
  --provider auto \
  --change "결제 API 장애 긴급 hotfix 배포가 필요합니다." \
  --users 1200 \
  --payment 1

• 성공판정:
  • parsed.parse_ok = true
  • parsed.risk = "high"
  • parsed.test = "FULL_REGRESSION"에 근접한 결과

4) 배치 평가 (재현성 점검)

• 도구: day7_release_gate_handson.py, sample_tasks_day7.json
• 입력: 샘플 변경요청 3건(기대값 포함)
• 실행명령:

python day7_release_gate_handson.py \
  --mode eval \
  --provider auto \
  --input sample_tasks_day7.json

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

5) 실무 확장 포인트

• 팀별 릴리즈 정책을 도구 함수에 반영 (payment_path 외에 db_migration, rollback_ready 등)
• 변경요청 입력을 Jira/Linear 필드와 매핑
• eval 결과를 주간 운영 지표로 누적(배포 실패율과 함께 관리)

현장형 미니 사례

사례 A) 핫픽스인데 테스트 범위가 과소 제안된 경우

운영 중 결제 장애였지만 users 값이 낮아 중간 리스크로 분류됐다. payment=1 조건에 강한 가중치를 주고 hotfix 키워드 우선순위를 올리자 잘못된 제안이 줄었다.

사례 B) 배포 윈도우 추천이 팀 운영시간과 충돌한 경우

에이전트가 심야 윈도우를 추천했지만 팀 온콜 체계와 맞지 않아 실행이 지연됐다. 팀 캘린더/근무규칙을 반영한 윈도우 맵을 추가해 운영 적합성이 올라갔다.

25분 보강 루틴

• 5분: 최근 배포 실패/지연 2건 회고
• 5분: 리스크 규칙(assess_release_risk) 보정
• 5분: 테스트 정책(choose_test_plan) 커스터마이즈
• 5분: sample_tasks_day7.json에 실제 변경요청 2건 추가
• 5분: eval 재실행 후 score와 실패원인 기록

---

트러블슈팅 (자주 막히는 5가지)

1. ModuleNotFoundError: dotenv / smolagents

   • 원인: 가상환경 미활성 또는 의존성 미설치
   • 해결:

     source .venv/bin/activate
     pip install -r requirements.txt

2. 모델 키를 찾지 못했습니다 런타임 에러

   • 원인: .env에 OPENAI_API_KEY/HF_TOKEN 없음
   • 해결: 프로젝트 루트 또는 실행 경로에 .env 생성 후 키 설정

3. No such file or directory (이모지/공백 경로)

   • 원인: 🤗 HF-Agents-Course 경로 인용(quoting) 누락
   • 해결: 경로 전체를 따옴표로 감싸거나 공백 이스케이프(\ ) 사용

4. parse_ok = false

   • 원인: 모델 출력 마지막 줄이 FINAL: 계약 형식을 지키지 않음
   • 해결: 프롬프트의 출력 계약 문구를 유지하고, FINAL 정규식 조건을 임의 변경하지 않기

5. 입력 JSON 루트는 list여야 합니다

   • 원인: sample_tasks_day7.json 루트 구조가 객체({})로 바뀜
   • 해결: 루트를 배열([])로 유지하고 각 항목에 expected 필드 포함

---

체크리스트

• selfcheck 성공 (tools_ok=true)
• single 모드에서 parse_ok=true 확인
• eval 점수(score) 기록
• 팀 정책(리스크 기준/배포 윈도우) 1개 이상 커스터마이즈

참고 링크 (우선순위)

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

실습 파일 다운로드

• Day7 실습 가이드 README
• day7_release_gate_handson.py
• sample_tasks_day7.json
• hf-agents-day7-release-gate-handson.zip

보강 추가: 팀 캘린더/온콜 정책 YAML 예시

배포 윈도우 추천을 현실화하려면 팀 운영 규칙을 데이터로 고정하는 게 좋다.

release_policy:
  timezone: "Asia/Seoul"
  preferred_windows:
    weekday: ["10:00-11:30", "14:00-16:00"]
    friday: ["10:00-12:00"]
  blocked_windows:
    - "weekday 12:00-13:00"   # 점심
    - "weekday 18:30-09:30"   # 야간
 
oncall:
  required: true
  min_engineers: 2
  payment_path_requires_senior: true
 
risk_rules:
  high_requires:
    - "FULL_REGRESSION"
    - "rollback_plan"
    - "oncall_ack"

이 YAML을 기준으로 choose_deploy_window를 튜닝하면, 추천 결과가 팀 운영과 충돌하는 빈도를 줄일 수 있다.

품질 점검표 (2026-02-28)

• 재현성: 9.0/10
• 공식 근거 연결: 9.0/10
• 운영 적용성: 9.5/10
• 문서 가독성: 9.0/10

즉시 보강 포인트 1개

• YAML 정책 변경 전/후로 추천 윈도우가 어떻게 달라지는지 비교 로그 예시를 추가해 운영자 이해도를 높인다.

생성형 AI 활용 고지

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