🤗 33. 본편 20: smolagents 도구결과 검증 게이트로 환각 줄이기

이번 편은 에이전트가 도구를 호출한 뒤, 결과를 바로 믿지 않고 **검증 게이트(validate gate)**를 거쳐 신뢰도를 높이는 방법을 다룬다.

• 이전 편: 🤗 32. 본편 19

flowchart LR
  A[사용자 요청] --> B[CodeAgent]
  B --> C[fetch_price 도구 호출]
  C --> D[원시 결과]
  D --> E{검증 게이트\n필수 필드/타입/범위}
  E -- 통과 --> F[result.json 저장]
  E -- 실패 --> G[에러 사유 반환\n재시도 유도]

실습 목표

1. 도구 결과를 JSON 스키마로 검증한다.
2. 검증 실패 시 즉시 실패 처리하고 원인을 남긴다.
3. 성공 시 result.json으로 남겨 자동화 파이프라인에 연결한다.

---

1) 준비

Step 1-1. 작업 폴더 생성

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

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

• 성공판정:

pwd

출력이 ~/hf-agents-day20

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. day20_validation_gate.py 저장

• 도구: Python 파일
• 입력: 아래 코드

import json
from pathlib import Path
from datetime import datetime
 
from smolagents import CodeAgent, HfApiModel, tool
 
RESULT_PATH = Path("result.json")
 
 
@tool
def fetch_price(product: str) -> str:
    """상품 이름을 받아 가격 정보를 JSON 문자열로 반환한다."""
    mock_db = {
        "keyboard": {"product": "keyboard", "price": 59000, "currency": "KRW"},
        "mouse": {"product": "mouse", "price": 32000, "currency": "KRW"},
    }
    data = mock_db.get(product.lower(), {"product": product, "price": -1, "currency": ""})
    return json.dumps(data, ensure_ascii=False)
 
 
def validate_payload(payload: dict) -> tuple[bool, str]:
    required = ["product", "price", "currency"]
    for key in required:
        if key not in payload:
            return False, f"missing:{key}"
 
    if not isinstance(payload["price"], int):
        return False, "price_not_int"
    if payload["price"] <= 0:
        return False, "price_out_of_range"
    if payload["currency"] not in ["KRW", "USD", "EUR"]:
        return False, "currency_not_allowed"
 
    return True, "ok"
 
 
def build_agent() -> CodeAgent:
    model = HfApiModel("Qwen/Qwen2.5-72B-Instruct")
    return CodeAgent(
        tools=[fetch_price],
        model=model,
        max_steps=5,
        additional_authorized_imports=["json"],
    )
 
 
if __name__ == "__main__":
    product = "keyboard"
 
    prompt = f"""
너는 가격조회 어시스턴트다.
반드시 fetch_price('{product}')를 호출하고,
도구 결과를 그대로 JSON으로 반환해.
설명 문장 없이 JSON만 출력.
"""
 
    agent = build_agent()
    raw = agent.run(prompt)
 
    if isinstance(raw, str):
        cleaned = raw.strip().removeprefix("```json").removesuffix("```").strip()
        payload = json.loads(cleaned)
    else:
        payload = raw
 
    ok, reason = validate_payload(payload)
    output = {
        "ok": ok,
        "reason": reason,
        "checked_at": datetime.utcnow().isoformat() + "Z",
        "data": payload,
    }
 
    RESULT_PATH.write_text(json.dumps(output, ensure_ascii=False, indent=2), encoding="utf-8")
    print("saved: result.json")
 
    if not ok:
        raise SystemExit(f"validation_failed:{reason}")

• 성공판정:

python -m py_compile day20_validation_gate.py

오류 없이 종료되면 통과

---

3) 실행 및 검증

Step 3-1. 정상 케이스 실행

• 도구: Python
• 입력: 기본값 product = "keyboard"
• 실행명령:

python day20_validation_gate.py
cat result.json

• 성공판정:
  • saved: result.json 출력
  • result.json의 ok가 true
  • reason이 ok

Step 3-2. 실패 케이스 확인(검증 게이트 동작)

• 도구: 파일 편집 + Python
• 입력: product = "unknown_item"로 변경
• 실행명령:

# 코드에서 product 값을 unknown_item으로 바꾼 뒤
python day20_validation_gate.py

• 성공판정:
  • 프로세스가 validation_failed:price_out_of_range로 종료
  • result.json에 ok: false 기록

---

초보자용 쉬운 설명

• 에이전트가 도구를 잘 호출해도, 결과값이 비정상일 수 있다.
• 그래서 “도구 호출 성공”과 “업무에 쓸 수 있는 값”을 분리해서 본다.
• 검증 게이트는 이 둘을 분리해 자동화 사고를 줄여준다.

실무 적용 포인트

1. 정산/가격/재고 자동화: 범위 밖 숫자를 즉시 차단.
2. 티켓 라우팅: 필수 필드 누락 시 사람 검토 큐로 보냄.
3. API 비용 절감: 잘못된 결과를 후속 단계로 넘기지 않아 재처리 비용 감소.

체크리스트

• smolagents 설치 완료
• day20_validation_gate.py 문법 검사 통과
• 정상 케이스에서 ok=true 확인
• 실패 케이스에서 validation_failed 종료 확인
• result.json에 ok/reason/data 구조 확인

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성했고, 실습 절차(도구/입력/실행명령/성공판정)와 예시 코드는 사람이 검토해 확정했다.