🤗 10. 실습편 02: 휴먼 핸드오프 + 가드레일 미니 프로젝트 핸즈온

이번 편은 **“에이전트가 어디까지 자동 처리하고, 어디서 사람에게 넘길지”**를 구현하는 실습이다.
실무에서 가장 중요한 안전장치인 휴먼 핸드오프(Human Handoff) + PII 마스킹 가드레일을 미니 프로젝트로 재현한다.

• 이전 편: 🤗 09. 본편 04

한 줄 결론

규칙 기반 핸드오프 정책을 먼저 고정하고(selfcheck → single → eval), 그다음 모델 에이전트(smolagents)로 확장하면 초보자도 안전한 자동화 파이프라인을 만들 수 있다.

flowchart LR
  A[고객 요청 입력] --> B[리스크/PII/금액 판별]
  B --> C{핸드오프 필요?}
  C -- No --> D[AUTO_REPLY]
  C -- Yes --> E[HUMAN_HANDOFF]
  E --> F[ops-review 큐 전달]
  B --> G[PII 마스킹 규칙]
  G --> D
  G --> E

---

실습 목표

• 휴먼 핸드오프 정책(고위험/분쟁/PII)을 코드로 명시한다.
• 결과를 FINAL: 계약 문자열로 고정해 파싱 가능하게 만든다.
• 배치 평가(eval)로 재현성을 점검한다.

실습 파일

• Day10 실습 가이드 README
• day10_handoff_guardrail_handson.py
• sample_tasks_day10.json

---

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
pip install -r requirements.txt

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

2) 셀프체크 실행 (정책 기본 검증)

• 도구: day10_handoff_guardrail_handson.py
• 입력: 내장 2개 케이스
• 실행명령:

python3 day10_handoff_guardrail_handson.py --mode selfcheck

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

3) 단일 요청 테스트 (핸즈온)

• 도구: day10_handoff_guardrail_handson.py
• 입력:
  • text: 고객 카드 결제 분쟁으로 환불 요청
  • priority: high
  • pii: 1
  • amount: 1200000
• 실행명령:

python3 day10_handoff_guardrail_handson.py \
  --mode single \
  --text "고객 카드 결제 분쟁으로 환불 요청" \
  --priority high \
  --pii 1 \
  --amount 1200000

• 성공판정:
  • result.action = "HUMAN_HANDOFF"
  • result.masking = "REQUIRED"
  • result.final이 FINAL: 형식 유지

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

• 도구: sample_tasks_day10.json
• 입력: 3개 샘플 태스크
• 실행명령:

python3 day10_handoff_guardrail_handson.py --mode eval --input sample_tasks_day10.json

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

---

코드에서 꼭 볼 포인트

1. classify()
   • priority, pii, amount, 분쟁 키워드 기반으로 AUTO_REPLY/HUMAN_HANDOFF 결정
2. masking
   • PII 입력 시 REQUIRED 강제
3. final
   • FINAL: action=... 계약 문자열 고정 (후처리 파서 안정화)

smolagents 확장 아이디어 (다음 단계)

• 현재 규칙 함수를 Tool로 래핑해 ToolCallingAgent에 연결
• 검토 큐(ops-review)를 Jira/Slack/n8n 노드로 연동
• eval 실패 케이스를 주간 회고 데이터로 누적

---

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

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

   • 원인: 🤗 HF-Agents-Course 경로 인용 누락
   • 해결: 경로 전체를 큰따옴표로 감싸 실행

2. invalid priority 에러

   • 원인: --priority urgent처럼 허용 외 값 사용
   • 해결: low|medium|high|critical 중 하나로 입력

3. eval에서 input JSON root must be list

   • 원인: sample_tasks_day10.json 루트가 객체({})로 변경됨
   • 해결: 루트를 배열([])로 유지

4. single 결과가 AUTO_REPLY로만 나옴

   • 원인: --pii 1 또는 고위험 키워드/금액 조건이 빠짐
   • 해결: 테스트 입력에 pii=1, priority=high, 분쟁 키워드를 포함

5. 가상환경 패키지 설치 실패

   • 원인: 시스템 pip/권한 혼용
   • 해결: source .venv/bin/activate 후 pip install -r requirements.txt 재실행

---

체크리스트

• selfcheck_ok=true 확인
• single 모드에서 HUMAN_HANDOFF + masking=REQUIRED 확인
• eval 점수(score) 기록
• 팀 정책 기준(금액/키워드/우선순위) 1개 이상 커스터마이즈

참고 링크 (우선순위)

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

생성형 AI 활용 고지

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