🤗 04. 실습편 01: 업무요청 라우팅 미니 프로젝트

이번 실습편은 Hugging Face Agents Course 이론(툴 선택, 실행 루프, 관찰/검증)을 작게 재현 가능한 미니 프로젝트로 옮기는 1편이다. 목표는 “요청을 읽고 적절한 도구를 고르는 라우팅 에이전트”를 직접 실행해 보고, 정확도 개선(baseline → contract)을 수치로 확인하는 것이다.

flowchart TD
  A[사용자 요청] --> B{라우터 규칙}
  B -->|문서조회| C[search_docs]
  B -->|수식/예산| D[calculate]
  B -->|답장/공지| E[draft_reply]
  C --> F[결과 관찰]
  D --> F
  E --> F
  F --> G[성공판정: 정확도/오류율]
  G -->|개선 필요| H[라우터 규칙 수정]
  H --> B

공식 근거 바로보기

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

0) 실습 목표

• 도구 3개(search_docs, calculate, draft_reply)를 가진 라우팅 에이전트를 실행한다.
• 동일 입력에서 baseline_accuracy와 contract_accuracy를 비교한다.
• 성공 판정 기준(재현 가능)을 통과한다.

1) 사전 준비

• 도구: Python 3.10+, 터미널, Git(선택)
• 입력:
  • day4_mini_project_agent.py
  • sample_tasks_day4.json
  • 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) 미니 프로젝트 배치 평가 실행

• 도구: day4_mini_project_agent.py
• 입력: sample_tasks_day4.json (요청 8개)
• 실행명령:

python day4_mini_project_agent.py --mode eval --input sample_tasks_day4.json

• 성공판정:
  • 출력 JSON에 improved: true
  • contract_accuracy >= 0.75
  • pass: true

기준 샘플 결과: baseline_accuracy=0.375, contract_accuracy=1.0

3) 단일 요청 핸즈온

• 도구: day4_mini_project_agent.py
• 입력: 임의 업무 요청 1개
• 실행명령:

python day4_mini_project_agent.py --mode single --request "이번 달 비용 99000 + 12000 계산해줘"

• 성공판정:
  • chosen_tool이 요청 유형과 일치(예: 계산 요청이면 calculate)
  • ok: true

4) 본인 업무 데이터로 확장

• 도구: sample_tasks_day4.json, 코드 편집기
• 입력: 실제 업무 요청 10개 이상(문서조회/계산/답장 혼합)
• 실행명령:

python day4_mini_project_agent.py --mode eval --input sample_tasks_day4.json

• 성공판정:
  • contract_accuracy가 기존보다 상승 또는 유지
  • 오분류 케이스 원인을 설명할 수 있음(키워드 누락/모호한 요청 등)

5) 현장형 미니 사례

사례 A) 계산요청이 문서조회로 자주 빠지던 팀

요청문에 “정산”, “원가”, “합계” 같은 도메인 표현이 많아 기존 키워드 셋으로는 계산 의도를 놓쳤다. contract_router()에 현업 용어를 추가하고 우선순위를 조정하자 정확도가 눈에 띄게 개선됐다.

사례 B) 답장 초안 품질이 들쭉날쭉하던 팀

draft_reply 출력 형식을 자유 텍스트로 두어 후처리 파이프라인이 불안정했다. tone, main_point, next_action 필드를 고정한 후 재작업률이 줄었다.

6) 트러블슈팅 (실습 중 자주 막히는 5가지)

1. ModuleNotFoundError 발생

   • 원인: 가상환경 미활성 또는 패키지 설치 누락
   • 해결: source .venv/bin/activate 후 pip install -r requirements.txt

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

   • 원인: 🤗 HF-Agents-Course 경로 공백/이모지 이스케이프 누락
   • 해결: 경로를 따옴표로 감싸거나 🤗\ HF-Agents-Course 형태로 이스케이프

3. 입력 JSON은 list 형식이어야 합니다 에러

   • 원인: sample_tasks_day4.json 루트 구조가 객체({})로 바뀜
   • 해결: 루트는 반드시 배열([]) 유지, 각 항목에 request, expected_tool 포함

4. 계산 요청인데 search_docs로 라우팅됨

   • 원인: 라우터 키워드 규칙에 도메인 표현 누락
   • 해결: contract_router()의 calc_keywords에 현업 표현(정산/원가/세금 등) 추가

5. ZeroDivisionError 또는 수식 파싱 실패

   • 원인: 잘못된 수식 입력(예: 10/0, 문자 섞인 수식)
   • 해결: 입력 전 검증 규칙 추가, 실패 시 재입력 안내 메시지 반환

칠판 치트시트

라우팅 에이전트 품질은 “모델 성능”보다 “규칙 품질”이 먼저다.

• 요청 분류 기준을 명시(문서/계산/답장)
• 도구별 성공 기준을 숫자로 정의
• 실패를 예외가 아닌 정상 분기로 처리
• baseline vs contract를 매번 비교해 개선 여부를 수치화

20분 보강 루틴

• 5분: 오분류 상위 3개 케이스 추출
• 5분: contract_router 키워드/우선순위 보정
• 5분: sample_tasks_day4.json에 실제 업무 3건 추가
• 5분: --mode eval 재실행 후 점수/실패원인 기록

실습 파일 다운로드

• Day4 실습 가이드 README
• day4_mini_project_agent.py
• sample_tasks_day4.json
• hf-agents-day4-mini-project.zip

참고 링크 (우선순위)

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

보강 추가: 난이도 레이블 운영 예시

배치 평가를 더 빨리 해석하려면 샘플 태스크에 난이도 레이블을 넣는 게 효과적이다.

예시(sample_tasks_day4.json):

[
  {"request":"이번 달 비용 99000+12000 계산", "expected_tool":"calculate", "difficulty":"easy"},
  {"request":"환불 규정 문서 찾아 요약", "expected_tool":"search_docs", "difficulty":"medium"},
  {"request":"결제 오류 안내 메일 초안 + 톤 완화", "expected_tool":"draft_reply", "difficulty":"hard"}
]

해석 템플릿:

• easy 정확도 ≥ 0.9
• medium 정확도 ≥ 0.8
• hard 정확도 ≥ 0.7

이렇게 보면 전체 점수는 비슷해도, 실제 병목 구간(보통/어려움)을 더 빨리 찾을 수 있다.

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

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

즉시 보강 포인트 1개

• 난이도별 오분류 Top3를 자동 출력하는 요약 스크립트(또는 표 템플릿)를 추가해 회고 시간을 더 줄인다.

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 작성 및 구조화를 수행했으며, 최종 공개 전 사람이 검토·보정한다.