🤗 31. 실습편 09: smolagents 도구호출 검증 루프 미니프로젝트 핸즈온 1

이번 편은 **“요청을 받아 도구를 호출하고, 결과를 검증해 PASS/RETRY를 내는 QA 미니 프로젝트”**를 재현한다.
핵심은 CodeAgent + @tool + 품질 게이트를 묶어, 결과를 자동으로 검증 가능한 형태(JSON)로 남기는 것이다.

• 이전 편: 🤗 30. 본편 18
• 다음 편 예고: 실습편 09-2 (다중 입력 배치 평가 + 실패 케이스 리포트)

flowchart TD
  A[task.txt 입력] --> B[CodeAgent]
  B --> C[tool: normalize_request]
  C --> D[tool: make_answer]
  D --> E[tool: validate_answer]
  E --> F{valid?}
  F -- yes --> G[qa_result.json 저장]
  F -- no --> H[RETRY 사유 기록]
  H --> G

0) 실습 목표

task.txt를 입력하면 qa_result.json에 아래 4개 필드가 생성되도록 만든다.

• request_normalized
• answer
• valid (true/false)
• reason

---

1) 환경 준비

• 도구: 터미널
• 입력: Python 3.10+
• 실행명령:

mkdir -p ~/hf-agents-lab31
cd ~/hf-agents-lab31
python3 -m venv .venv
source .venv/bin/activate
pip install -U "smolagents[toolkit]" litellm

• 성공판정:

python -V
pip show smolagents | head -n 5

2) 모델 설정

• 도구: 터미널
• 입력: API 키, 모델 ID
• 실행명령:

export OPENAI_API_KEY="YOUR_API_KEY"
export MODEL_ID="openai/gpt-4o-mini"

• 성공판정:

python - <<'PY'
import os
print('MODEL_ID =', os.getenv('MODEL_ID'))
print('OPENAI_API_KEY set =', bool(os.getenv('OPENAI_API_KEY')))
PY

3) 입력 데이터 준비

• 도구: 터미널
• 입력: 사용자 요청 샘플
• 실행명령:

cat > task.txt <<'TXT'
다음주 월요일 오전 9시에 제품 데모 회의 잡아줘. 참석자는 minji@acme.ai, dev@acme.ai야.
TXT

• 성공판정:

cat task.txt

4) 미니 프로젝트 코드 작성

• 도구: 에디터/터미널
• 입력: 아래 코드
• 실행명령:

cat > lab31_tool_validation_agent.py <<'PY'
from __future__ import annotations
 
import json
import os
from pathlib import Path
 
from smolagents import CodeAgent, LiteLLMModel, tool
 
INPUT_PATH = Path("task.txt")
OUTPUT_PATH = Path("qa_result.json")
 
 
@tool
def normalize_request(text: str) -> str:
    """요청 문장을 실행 가능한 한 줄 포맷으로 정규화한다."""
    return " ".join(text.strip().split())
 
 
@tool
def make_answer(normalized: str) -> str:
    """정규화된 요청 기반의 실행 제안 답변을 만든다."""
    return f"회의 생성 요청 접수: {normalized}"
 
 
@tool
def validate_answer(answer: str) -> str:
    """답변 최소 품질을 검증하고 JSON 문자열을 반환한다."""
    valid = all(k in answer for k in ["회의", "요청", "접수"])
    reason = "PASS" if valid else "필수 키워드 누락"
    return json.dumps({"valid": valid, "reason": reason}, ensure_ascii=False)
 
 
def strip_code_fence(text: str) -> str:
    t = text.strip()
    if t.startswith("```"):
        lines = t.splitlines()
        if lines and lines[0].startswith("```"):
            lines = lines[1:]
        if lines and lines[-1].startswith("```"):
            lines = lines[:-1]
        t = "\n".join(lines).strip()
    return t
 
 
def main() -> None:
    raw = INPUT_PATH.read_text(encoding="utf-8")
 
    model = LiteLLMModel(model_id=os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
    agent = CodeAgent(
        tools=[normalize_request, make_answer, validate_answer],
        model=model,
        max_steps=6,
        additional_authorized_imports=["json"],
    )
 
    prompt = f"""
아래 요청을 처리해 최종 JSON만 반환하라.
 
요청:
{raw}
 
필수 절차:
1) normalize_request 호출
2) make_answer 호출
3) validate_answer 호출
 
최종 출력 스키마:
{{
  "request_normalized": "string",
  "answer": "string",
  "valid": true,
  "reason": "string"
}}
 
주의:
- JSON 외 텍스트 금지
"""
 
    result = agent.run(prompt)
    obj = json.loads(strip_code_fence(str(result)))
 
    OUTPUT_PATH.write_text(json.dumps(obj, ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"saved: {OUTPUT_PATH}")
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • CodeAgent, @tool, validate_answer 함수 존재

5) 실행

• 도구: Python
• 입력: task.txt
• 실행명령:

python lab31_tool_validation_agent.py
cat qa_result.json

• 성공판정:
  • saved: qa_result.json 출력
  • JSON에 4개 필드 모두 존재

6) 품질 게이트 검증

• 도구: Python
• 입력: qa_result.json
• 실행명령:

python - <<'PY'
import json
obj = json.load(open('qa_result.json', encoding='utf-8'))
 
for key in ['request_normalized', 'answer', 'valid', 'reason']:
    assert key in obj, f'missing: {key}'
 
assert isinstance(obj['request_normalized'], str) and obj['request_normalized'].strip()
assert isinstance(obj['answer'], str) and obj['answer'].strip()
assert isinstance(obj['valid'], bool)
assert isinstance(obj['reason'], str)
 
print('PASS: 품질 게이트 통과')
PY

• 성공판정:
  • PASS: 품질 게이트 통과

---

트러블슈팅 (실전 4선)

1. AuthenticationError / 호출 실패

• 원인: OPENAI_API_KEY 미설정 또는 모델 ID 오타
• 조치:

python - <<'PY'
import os
print(bool(os.getenv('OPENAI_API_KEY')), os.getenv('MODEL_ID'))
PY

2. ModuleNotFoundError: smolagents

• 원인: 가상환경 미활성화
• 조치:

source .venv/bin/activate
pip install -U "smolagents[toolkit]" litellm

3. json.loads 파싱 실패

• 원인: 모델이 JSON 외 설명 문장 출력
• 조치: 프롬프트에 JSON 외 텍스트 금지 유지, strip_code_fence() 유지

4. valid가 계속 false

• 원인: make_answer 출력 형식 변경으로 검증 규칙 불일치
• 조치: validate_answer 키워드 규칙과 make_answer 포맷을 같이 수정

체크리스트

• 환경 구성 완료
• lab31_tool_validation_agent.py 실행 성공
• qa_result.json 생성 확인
• 품질 게이트 PASS
• 트러블슈팅 3개 이상 점검

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI로 초안을 작성하고, 사람이 실습 재현성(도구/입력/실행명령/성공판정), 오류 대응, 링크 및 내부 연결을 검토해 확정했다.