🤗 29. 본편 17: smolagents ToolCallingAgent 실무형 고객문의 분류 자동화

이번 편은 ToolCallingAgent로 고객문의를 자동 분류하는 가장 실무적인 입문 패턴을 다룬다.
핵심은 “예쁘게 답하기”가 아니라, 카테고리/우선순위를 안정적으로 뽑아 후속 자동화에 연결하는 것이다.

flowchart LR
  A[inquiries.jsonl 입력] --> B[ToolCallingAgent]
  B --> C[classify_inquiry 도구]
  C --> D[카테고리/우선순위 JSON]
  D --> E[save_result 도구]
  E --> F[triage_results.jsonl 저장]
  F --> G[사람 검토 후 티켓 시스템 반영]

실습 목표

1. ToolCallingAgent를 실행한다.
2. 문의 텍스트를 분류하는 커스텀 도구를 연결한다.
3. 결과를 triage_results.jsonl로 저장한다.
4. 성공 판정(파일 생성, 라인 수 일치, 필수 필드 존재)으로 재현성을 확인한다.

---

1) 준비

Step 1-1. 작업 폴더 생성

• 도구: 터미널
• 입력: 없음
• 실행명령:

mkdir -p ~/hf-agents-day17 && cd ~/hf-agents-day17

• 성공판정: pwd가 ~/hf-agents-day17

Step 1-2. 가상환경 + 패키지 설치

• 도구: Python 3.10+
• 입력: 없음
• 실행명령:

python3 -m venv .venv
source .venv/bin/activate
pip install -U smolagents

• 성공판정:

python -c "import smolagents; print('OK')"

출력 OK

Step 1-3. 모델 인증 키 설정

• 도구: 환경변수
• 입력: HF_TOKEN
• 실행명령:

export HF_TOKEN="hf_xxx"

• 성공판정:

echo ${HF_TOKEN:+set}

출력 set

---

2) 샘플 문의 데이터 생성

Step 2-1. inquiries.jsonl 만들기

• 도구: 텍스트 파일
• 입력: 아래 샘플
• 실행명령:

cat <<'JSONL' > inquiries.jsonl
{"id":"q1","text":"결제는 됐는데 주문확인이 안 떠요"}
{"id":"q2","text":"어제 받은 키보드가 입력이 안 됩니다"}
{"id":"q3","text":"세금계산서 발행 방법 알려주세요"}
{"id":"q4","text":"배송이 3일째 멈춰 있어요"}
JSONL

• 성공판정:

wc -l inquiries.jsonl

4 inquiries.jsonl이면 정상.

---

3) 에이전트 코드 작성

Step 3-1. day17_triage.py 저장

• 도구: Python 파일
• 입력: 아래 코드
• 실행명령: 파일 생성 후 저장

import json
from pathlib import Path
 
from smolagents import ToolCallingAgent, HfApiModel, tool
 
 
@tool
def classify_inquiry(text: str) -> str:
    """문의 텍스트를 카테고리와 우선순위로 분류해 JSON 문자열로 반환한다."""
    t = text.strip()
    if any(k in t for k in ["안 돼", "불량", "고장", "입력"]):
        result = {"category": "제품문제", "priority": "high"}
    elif any(k in t for k in ["결제", "주문확인", "환불"]):
        result = {"category": "주문/결제", "priority": "high"}
    elif any(k in t for k in ["배송", "택배", "도착"]):
        result = {"category": "배송", "priority": "medium"}
    else:
        result = {"category": "일반문의", "priority": "low"}
    return json.dumps(result, ensure_ascii=False)
 
 
@tool
def save_result(path: str, line: str) -> str:
    """JSONL 라인을 파일 끝에 추가 저장한다."""
    with open(path, "a", encoding="utf-8") as f:
        f.write(line + "\n")
    return f"saved:{path}"
 
 
def build_agent() -> ToolCallingAgent:
    model = HfApiModel("Qwen/Qwen2.5-72B-Instruct")
    return ToolCallingAgent(
        tools=[classify_inquiry, save_result],
        model=model,
        max_steps=6,
    )
 
 
if __name__ == "__main__":
    in_path = Path("inquiries.jsonl")
    out_path = Path("triage_results.jsonl")
    if out_path.exists():
        out_path.unlink()
 
    agent = build_agent()
 
    for raw in in_path.read_text(encoding="utf-8").splitlines():
        item = json.loads(raw)
        prompt = f"""
다음 고객문의를 분류해.
문의: {item['text']}
 
규칙:
1) classify_inquiry 도구를 반드시 호출
2) 결과를 {{id, category, priority}} JSON 한 줄로 만들 것
3) save_result 도구로 triage_results.jsonl에 저장
"""
        result = agent.run(prompt)
        print(f"[DONE] {item['id']} -> {result}")
 
    print("[FINISH] triage completed")

• 성공판정:

python -m py_compile day17_triage.py

오류 없이 종료되면 통과.

---

4) 실행 및 검증

Step 4-1. 에이전트 실행

• 도구: day17_triage.py
• 입력: inquiries.jsonl
• 실행명령:

python day17_triage.py

• 성공판정: 출력 마지막에 [FINISH] triage completed 표시

Step 4-2. 결과 검증

• 도구: 터미널
• 입력: triage_results.jsonl
• 실행명령:

test -f triage_results.jsonl && echo "FILE_OK"
[ "$(wc -l < triage_results.jsonl)" -eq 4 ] && echo "COUNT_OK"
grep -E '"category"' triage_results.jsonl >/dev/null && echo "FIELD_OK"

• 성공판정: FILE_OK, COUNT_OK, FIELD_OK 3개 모두 출력

---

5) 초보자용 쉬운 설명

• ToolCallingAgent는 도구를 호출해서 정해진 형식 결과를 만들 때 특히 유리하다.
• 이번 실습에서 LLM은 “생각”을 하고, 실제 분류 규칙은 classify_inquiry가 담당한다.
• 그래서 출력 품질이 흔들려도, **최종 저장 구조(id/category/priority)**는 안정적으로 유지된다.

---

6) 실무 적용 포인트

1. CS 티켓 선분류 자동화: 카테고리별 담당자 라우팅 연결.
2. SLA 대응: priority=high만 즉시 알림(슬랙/문자)로 분기.
3. 운영 안정성: 결과를 JSONL로 고정해 BI/대시보드 연동이 쉽다.
4. 확장 경로: 다음 단계에서 FAQ 검색 도구를 추가해 1차 자동응답까지 연결 가능.

체크리스트

• 가상환경 생성 및 smolagents 설치 완료
• inquiries.jsonl 4줄 생성 확인
• day17_triage.py 문법 검사 통과
• 실행 후 triage_results.jsonl 생성
• 라인 수 일치(입력 4 = 출력 4)
• 사람이 샘플 2건 이상 수동 검토

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성했고, 예시 코드/절차/표현은 사람 검토 후 확정했다.