🤗 06. 본편 02: ToolCallingAgent로 안전한 업무 라우팅

이번 편의 핵심은 간단하다. CodeAgent(코드 실행형) 다음 단계로, ToolCallingAgent(JSON 호출형)를 써서 라우팅 안정성을 높이는 것이다.

이전 편(본편 01)이 “첫 실행”이었다면, 이번 편은 “실무형 운영 패턴”이다.

• 이전 편: 🤗 05. 본편 01

한 줄 결론

고객 문의/업무 요청처럼 정해진 도구를 안전하게 호출해야 하는 상황에서는 ToolCallingAgent가 초보자에게 더 예측 가능한 출발점이다.

공식 근거 바로보기

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

왜 이 주제가 중요한가

Hugging Face Agents Course(Unit 2 smolagents)와 smolagents 공식 문서에서 공통으로 강조하는 지점은 다음이다.

• CodeAgent: 유연하고 강력하지만, 코드 실행이 개입됨
• ToolCallingAgent: JSON 기반으로 구조화되어 검증/운영에 유리

즉, “복잡한 추론”보다 “정해진 업무 분기”가 중요한 팀이라면 ToolCallingAgent가 빠른 실무 적용점이 된다.

flowchart LR
  A[고객 문의 입력] --> B[detect_category]
  B --> C[assign_priority]
  C --> D[suggest_action]
  D --> E[FINAL: category/priority/action]
  E --> F[헬프데스크 큐/에스컬레이션]

쉬운 비유로 이해하기

• CodeAgent: 숙련 직원이 상황 보고 직접 스크립트까지 작성해서 처리
• ToolCallingAgent: 콜센터 상담사가 정해진 체크리스트(도구) 순서대로 처리

처음 운영 자동화를 붙일 때는 “자유도”보다 “일관성”이 먼저다.

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

실습 파일 경로: /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) 도구 로직 셀프체크

• 도구: day6_toolcalling_triage.py
• 입력: 내장 테스트(카테고리/우선순위/액션 코드)
• 실행명령:

python day6_toolcalling_triage.py --mode selfcheck

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

Step 3) 단일 요청 실행 (ToolCallingAgent)

• 도구: day6_toolcalling_triage.py
• 입력:
  • issue: 결제가 두 번 청구됐어요. 빠르게 확인해주세요.
  • tier: vip
  • outage: 0
• 실행명령:

# .env에 OPENAI_API_KEY 또는 HF_TOKEN 필요
python day6_toolcalling_triage.py \
  --mode single \
  --provider auto \
  --issue "결제가 두 번 청구됐어요. 빠르게 확인해주세요." \
  --tier vip \
  --outage 0

• 성공판정:
  • parsed.parse_ok = true
  • parsed.priority가 P1에 근접한 결과

Step 4) 배치 평가

• 도구: day6_toolcalling_triage.py, sample_tasks_day6.json
• 입력: 샘플 문의 3건(기대 category/priority/action 포함)
• 실행명령:

python day6_toolcalling_triage.py \
  --mode eval \
  --provider auto \
  --input sample_tasks_day6.json

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

초보자 실수 방지 체크포인트

1. .env 키 없이 single/eval 먼저 실행해서 실패
2. 프롬프트에 최종 출력 형식(FINAL 라인)을 안 박아서 파싱 실패
3. 기대값 JSON(sample_tasks_day6.json) 구조를 임의 변경해서 평가 오류

실무 적용 포인트

• 고객지원(CS) 티켓 triage: billing/technical/account 자동 분류
• 온콜 운영: P1/P2/P3 기준으로 에스컬레이션 자동화
• SLA 리포트: score를 주간 지표로 추적해 품질 개선

현장형 미니 사례

사례 A) VIP 결제 이슈 우선순위 누락

초기 규칙에서 tier=vip 반영이 약해 긴급도가 과소평가됐다. assign_priority에 고객등급 가중치를 넣자 P1 라우팅이 안정화됐다.

사례 B) FINAL 파싱 실패로 자동화 중단

모델 응답 마지막 줄 형식이 흔들려 파싱 실패가 발생했다. 출력 계약(FINAL: category|priority|action)을 강제하고 정규식 검증을 넣은 뒤 실패율이 줄었다.

25분 보강 루틴

• 5분: 지난주 오분류 3건 추출
• 5분: 카테고리/우선순위 규칙 보정
• 5분: sample_tasks_day6.json에 실제 문의 3건 추가
• 5분: --mode eval 재실행 후 점수 기록
• 5분: 실패 케이스를 팀 운영 룰 문서에 반영

적용 체크리스트

• selfcheck 성공
• 단일 요청에서 FINAL 형식 파싱 성공
• 배치 평가 점수 기록(score)
• 실제 팀 분류 기준(카테고리/우선순위)을 도구 함수에 반영

참고 링크 (우선순위)

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

실습 파일 다운로드

• Day6 실습 가이드 README
• day6_toolcalling_triage.py
• sample_tasks_day6.json
• hf-agents-day6-toolcalling-triage.zip

보강 추가: FINAL 파싱 실패 재현/복구

FINAL 계약이 흔들리면 자동화가 가장 먼저 멈춘다. 아래처럼 실패 케이스를 재현해 보면 복구 기준이 명확해진다.

실패 출력 예시

결론은 billing 이고 우선순위는 P1로 보입니다.
다음 조치는 refund_team으로 전달하세요.

• 문제: FINAL: 접두/구분자 계약이 없어 파싱 불가

정상 출력 예시

FINAL: billing|P1|handoff_refund_team

정규식 점검 예시

import re
line = "FINAL: billing|P1|handoff_refund_team"
ok = bool(re.match(r"^FINAL:\s*[^|]+\|P[123]\|.+$", line))
print(ok)  # True

운영에서는 단순히 모델 답변 품질보다, 이런 계약 유지 여부가 장애를 줄이는 핵심이다.

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

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

즉시 보강 포인트 1개

• FINAL 계약 위반 시 자동 재질의(re-ask) 프롬프트 템플릿을 추가해 운영 중단 시간을 더 줄인다.

생성형 AI 활용 고지

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