🤗 06. HF Agents Course 실습편 1 - 미니 프로젝트 핸즈온 (smolagents)

목표

HF Agents Course 내용을 기준으로, smolagents CodeAgent + 2개 툴(Web 검색/계산기) 조합의 실습형 미니 프로젝트를 재현한다.

실습 시나리오

질문: 2025년 노벨 물리학상 수상자 수와 각 소속 국가를 요약해줘
에이전트는 웹 검색으로 사실 수집 후 계산기 툴로 검증(개수 산출)하여 답한다.

flowchart TD
    A[User Question] --> B[CodeAgent]
    B --> C[WebSearch Tool]
    C --> B
    B --> D[Calculator Tool]
    D --> B
    B --> E[Final Answer + Evidence]

준비물

• Python 3.10+
• Hugging Face 계정 + HF_TOKEN
• 패키지: smolagents, duckduckgo-search

단계별 실습

1) 작업 폴더/가상환경

• 도구: 터미널
• 입력:

mkdir -p hf-agents-lab-01 && cd hf-agents-lab-01
python -m venv .venv
source .venv/bin/activate
pip install -U pip

• 성공 판정: 프롬프트에 (.venv) 표시

2) 라이브러리 설치

• 도구: 터미널
• 입력:

pip install smolagents duckduckgo-search

• 성공 판정: 설치 에러 없이 종료

3) 토큰 설정

• 도구: 터미널
• 입력:

export HF_TOKEN="hf_xxx"

• 성공 판정:

echo $HF_TOKEN | cut -c1-6

출력에 hf_ 접두사 확인

4) 실행 코드 작성

• 도구: 에디터
• 파일: run_lab01.py

from smolagents import CodeAgent, DuckDuckGoSearchTool, PythonInterpreterTool, InferenceClientModel
 
model = InferenceClientModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct")
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool(), PythonInterpreterTool()],
    model=model,
    add_base_tools=False,
)
 
question = "2025년 노벨 물리학상 수상자 수와 각 소속 국가를 요약해줘. 출처도 함께 적어줘."
result = agent.run(question)
print(result)

• 성공 판정: 파일 저장 완료

5) 실행

• 도구: 터미널
• 입력:

python run_lab01.py

• 성공 판정:
  • 답변에 수상자 수(정수) 포함
  • 국가 요약 포함
  • 출처 URL/명칭 포함

검증 체크리스트

• 검색 결과 기반 인용이 포함되었는가?
• 수상자 수를 계산/검증했는가?
• 답변이 한국어로 간결하게 정리되었는가?

트러블슈팅 (3+)

1. 401 Unauthorized 또는 모델 호출 실패

   • 원인: HF_TOKEN 누락/만료
   • 조치: echo $HF_TOKEN 확인 후 재발급/재설정

2. ModuleNotFoundError: smolagents

   • 원인: venv 미활성화 또는 설치 실패
   • 조치: source .venv/bin/activate && pip install smolagents

3. 검색 도구가 빈 결과 반환

   • 원인: 네트워크/쿼리 과도 축약
   • 조치: 질문을 영문 키워드로 보강(예: Nobel Prize in Physics 2025 laureates)

4. 실행은 되지만 답이 불안정함

   • 원인: 검색 근거 부족/모호 질의
   • 조치: 프롬프트에 출처 2개 이상, 모르면 모른다고 답 제약 추가

확장 과제

• 동일 질문을 영어/한국어 프롬프트로 비교
• 툴 호출 로그를 저장해 재현성 점검
• 본편 4의 ToolCallingAgent로 동일 과제 재구현

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성하고, 공식 문서/저장소 링크 기반으로 사람이 검토·보완했습니다.