🤗 09. HF Agents Course 실습편 1 - 미니 프로젝트 핸즈온 재현 가이드

목표

Hugging Face Agents Course 흐름을 따라, smolagents 기반 미니 프로젝트(도구형 에이전트)를 로컬에서 재현 가능하게 끝까지 실행합니다.

참고(우선순위):

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

실습 시나리오

요청: “서울 오늘 날씨를 확인하고, 우산 필요 여부를 한 줄로 판단해줘”

에이전트는 다음 도구를 사용합니다.

• get_weather(city): Open-Meteo API 호출
• summarize(text): 판단 문장 생성

flowchart TD
    A[사용자 요청 입력] --> B[CodeAgent 실행]
    B --> C[get_weather 도구 호출]
    C --> D[기온/강수확률 파싱]
    D --> E[summarize 도구 호출]
    E --> F[최종 답변 반환]

1) 준비

도구

• Python 3.10+
• pip
• (선택) .env 로드 도구

입력

• 위치: Seoul
• 모델: Qwen/Qwen2.5-Coder-32B-Instruct (Hugging Face Inference API 기준 예시)

실행 명령

mkdir -p ~/lab/hf-agents-mini && cd ~/lab/hf-agents-mini
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install smolagents requests python-dotenv

성공 판정

• pip show smolagents 결과가 출력됨
• 가상환경 프롬프트 (.venv) 확인

2) 코드 작성

mini_project.py

import os
import requests
from smolagents import CodeAgent, tool
from smolagents.models import InferenceClientModel
 
@tool
def get_weather(city: str) -> str:
    """도시명으로 현재 기온/강수확률을 조회한다."""
    geo = requests.get(
        "https://geocoding-api.open-meteo.com/v1/search",
        params={"name": city, "count": 1, "language": "en", "format": "json"},
        timeout=15,
    ).json()
 
    if not geo.get("results"):
        return f"도시를 찾지 못했습니다: {city}"
 
    lat = geo["results"][0]["latitude"]
    lon = geo["results"][0]["longitude"]
 
    weather = requests.get(
        "https://api.open-meteo.com/v1/forecast",
        params={
            "latitude": lat,
            "longitude": lon,
            "current": "temperature_2m,precipitation_probability",
        },
        timeout=15,
    ).json()
 
    current = weather.get("current", {})
    t = current.get("temperature_2m", "N/A")
    p = current.get("precipitation_probability", "N/A")
    return f"{city} 현재 기온 {t}°C, 강수확률 {p}%"
 
@tool
def summarize(text: str) -> str:
    """날씨 문장을 바탕으로 우산 필요 여부를 한 줄로 요약한다."""
    return f"요약: {text}. 강수확률이 50% 이상이면 우산 권장."
 
model = InferenceClientModel(
    model_id="Qwen/Qwen2.5-Coder-32B-Instruct",
    token=os.getenv("HF_TOKEN"),
)
 
agent = CodeAgent(
    model=model,
    tools=[get_weather, summarize],
)
 
if __name__ == "__main__":
    task = "서울 오늘 날씨를 확인하고 우산 필요 여부를 한 줄로 알려줘."
    result = agent.run(task)
    print(result)

성공 판정

• 파일 저장 완료
• 문법 오류 없음 (python -m py_compile mini_project.py 통과)

3) 실행

실행 명령

export HF_TOKEN="hf_xxx"
python mini_project.py

성공 판정

• 최종 출력에 서울 현재 기온 과 우산 관련 문구 포함
• 예외 종료 없이 프로세스 종료 코드 0

4) 검증 체크리스트

• 도구 호출 2개(get_weather, summarize)가 실제 사용됨
• 입력 도시를 바꿔도 동작함 (예: Busan)
• 강수확률 수치가 응답에 포함됨
• 한 줄 요약 결과가 생성됨

트러블슈팅 (3+)

1. 401 Unauthorized / 모델 호출 실패

   • 원인: HF_TOKEN 누락/만료
   • 해결: 새 토큰 재발급 후 export HF_TOKEN=... 재설정

2. ModuleNotFoundError: smolagents

   • 원인: 가상환경 미활성화 또는 설치 누락
   • 해결: source .venv/bin/activate && pip install smolagents

3. Open-Meteo 타임아웃 (ReadTimeout)

   • 원인: 네트워크 지연
   • 해결: timeout 15→30 증가, 재시도 로직 추가

4. 도시 검색 실패 (results 없음)

   • 원인: 입력 도시명 표기 이슈
   • 해결: 영문 표기 사용(예: Seoul, Busan) 또는 국가 코드 확장

확장 과제

• 도시 목록(서울/부산/대구)을 순차 평가해 우산 필요 도시만 출력
• ToolCallingAgent 버전으로 포팅해 호출 추적 로그 비교
• 결과를 Markdown 리포트 파일로 저장

---

생성형 AI 활용 고지: 이 문서는 생성형 AI로 초안을 구성한 뒤, 실습 재현성(명령/검증/오류 대응)을 기준으로 사람이 검토·수정했습니다.