🤗 26. 본편 15: smolagents 도구 신뢰성 테스트와 평가 루프

한 줄로 말하면, 에이전트 품질은 ‘잘 돌아간다’가 아니라 ‘반복 실행해도 같은 기준으로 통과한다’로 관리해야 한다.
이번 본편은 smolagents 기반 에이전트에 도구 테스트 + 평가 루프(eval) 를 붙여 실무 배포 전 신뢰도를 확보하는 방법을 다룬다.

왜 지금 평가 루프가 필요한가

• 에이전트는 같은 질문에도 도구 호출 순서가 달라질 수 있다.
• 결과 문장이 자연스러워도, 정답 조건을 놓칠 수 있다.
• 따라서 본문 생성 이전에 자동 판정 기준(성공/실패) 을 먼저 고정해야 한다.

flowchart LR
  A[요청 입력] --> B[CodeAgent 실행]
  B --> C[도구 호출 로그 수집]
  C --> D{평가 규칙 통과?}
  D -->|Yes| E[배포 후보]
  D -->|No| F[프롬프트/도구 수정]
  F --> B

---

실습 목표

1. smolagents로 간단한 업무 에이전트를 만든다.
2. 도구 단위 테스트(selfcheck)를 통과시킨다.
3. 샘플 과제 셋으로 평가(eval) 점수를 계산한다.
4. 통과 기준 미달 시 수정 포인트를 바로 찾는다.

---

1) 준비: 폴더/환경/패키지

Step 1-1. 작업 폴더 생성

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

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

• 성공판정: pwd 결과가 ~/hf-agents-day15

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 또는 OpenAI 호환 키
• 실행명령:

export HF_TOKEN="hf_xxx"
# 또는
export OPENAI_API_KEY="sk-xxx"

• 성공판정: 키가 비어 있지 않음 (echo ${HF_TOKEN:+set})

---

2) 예제 코드 작성 (도구 + 에이전트 + 평가)

아래 파일을 그대로 저장한다.

day15_eval_loop.py

import json
from dataclasses import dataclass
from typing import List, Dict
 
from smolagents import CodeAgent, HfApiModel, tool
 
 
@tool
def shipping_cost(weight_kg: float, distance_km: int, urgent: bool = False) -> str:
    """무게/거리/긴급 여부로 배송비를 계산한다."""
    base = 2500
    weight_fee = int(weight_kg * 400)
    distance_fee = int(distance_km * 3)
    urgent_fee = 3000 if urgent else 0
    total = base + weight_fee + distance_fee + urgent_fee
    return json.dumps({"total_krw": total}, ensure_ascii=False)
 
 
@tool
def policy_lookup(topic: str) -> str:
    """간단한 내부 정책 조회 도구"""
    table = {
        "refund": "개봉 전 7일 이내 전액 환불 가능",
        "delivery": "평일 15시 이전 주문은 당일 출고",
        "warranty": "전자제품 기본 보증 1년"
    }
    return table.get(topic.lower(), "정책 없음")
 
 
def build_agent():
    model = HfApiModel("Qwen/Qwen2.5-72B-Instruct")
    return CodeAgent(
        tools=[shipping_cost, policy_lookup],
        model=model,
        max_steps=6,
    )
 
 
def selfcheck_tools() -> Dict:
    s1 = json.loads(shipping_cost(2.0, 100, False))
    s2 = policy_lookup("refund")
    return {
        "shipping_tool_ok": s1["total_krw"] == 3600,
        "policy_tool_ok": "환불" in s2,
    }
 
 
@dataclass
class Case:
    q: str
    must_include: List[str]
 
 
def run_eval(agent, cases: List[Case]) -> Dict:
    results = []
    passed = 0
 
    for c in cases:
        out = str(agent.run(c.q))
        ok = all(token in out for token in c.must_include)
        passed += 1 if ok else 0
        results.append({"question": c.q, "ok": ok, "output": out})
 
    score = passed / len(cases)
    return {
        "total": len(cases),
        "passed": passed,
        "score": round(score, 2),
        "pass": score >= 0.67,
        "results": results,
    }
 
 
if __name__ == "__main__":
    tool_state = selfcheck_tools()
    print("[SELFHECK]", json.dumps(tool_state, ensure_ascii=False))
 
    agent = build_agent()
    eval_cases = [
        Case(
            q="무게 2kg, 거리 100km 일반 배송비를 계산해줘.",
            must_include=["3600"],
        ),
        Case(
            q="환불 정책 요약해줘.",
            must_include=["7일", "환불"],
        ),
        Case(
            q="무게 1kg, 거리 50km, 긴급 배송비 계산 후 한 줄 요약.",
            must_include=["6050"],
        ),
    ]
 
    report = run_eval(agent, eval_cases)
    print("[EVAL]", json.dumps(report, ensure_ascii=False, indent=2))

---

3) 실행: selfcheck → eval

Step 3-1. 도구 단위 점검

• 도구: day15_eval_loop.py
• 입력: 없음
• 실행명령:

python day15_eval_loop.py

• 성공판정: [SELFHECK](오탈자 그대로 출력될 수 있음) 결과에서 아래 둘 다 true
  • shipping_tool_ok
  • policy_tool_ok

Step 3-2. 평가 결과 확인

• 도구: 같은 실행 로그의 [EVAL] JSON
• 입력: 내장 3개 테스트 케이스
• 실행명령: Step 3-1과 동일
• 성공판정:
  • score >= 0.67
  • pass: true

---

4) 초보자용 해설 (쉽게 이해하기)

• @tool 함수는 에이전트가 꺼내 쓰는 작은 계산기/사전이다.
• selfcheck_tools()는 도구가 망가지지 않았는지 확인하는 기본 건강검진이다.
• run_eval()은 질문 묶음을 돌려보고, 정해둔 키워드가 있는지로 통과를 정하는 채점기다.

즉, “한 번 잘된 데모”가 아니라 “매번 통과하는 시스템”으로 바꾸는 과정이 평가 루프다.

---

5) 실무 적용 포인트

1. 릴리즈 게이트: 배포 전 score 미달이면 자동 중단.
2. 회귀 방지: 프롬프트 수정 후에도 기존 케이스를 다시 돌려 품질 하락 감지.
3. 운영 로그 표준화: [SELFHECK], [EVAL] 같이 파싱 가능한 고정 키를 두면 대시보드 연동이 쉬움.
4. 테스트 케이스 분리: 이후 eval_cases.json 파일로 분리해 팀에서 공동 관리.

---

체크리스트

• 가상환경 생성/활성화 완료
• smolagents import 성공
• HF_TOKEN 또는 API 키 설정 완료
• selfcheck 2개 항목 true
• eval score 0.67 이상
• 실패 케이스 1개 이상 원인 기록

---

참고 링크 (우선순위)

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

생성형 AI 활용 고지

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