🤗 03. HF Agents Course 실습편 1 - 미니 프로젝트로 도구형 에이전트 완주

목표: smolagents로 웹 검색 + 계산 + 요약을 수행하는 미니 에이전트를 로컬에서 재현한다.

0) 준비물

• Python 3.10+
• 가상환경(venv/conda)
• Hugging Face 계정 및 토큰(필요 시)

1) 환경 세팅

도구

• smolagents
• (선택) duckduckgo-search

입력

• 새 프로젝트 폴더

실행 명령

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install smolagents duckduckgo-search

성공 판정

• python -c "import smolagents; print('ok')" 출력이 ok

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

입력

• 파일명: mini_agent.py

코드

from smolagents import CodeAgent, DuckDuckGoSearchTool, PythonInterpreterTool
 
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool(), PythonInterpreterTool()],
    add_base_tools=True,
)
 
prompt = "2026년 기준 Hugging Face Agents Course 핵심 모듈 3개를 찾아 한 줄 요약하고, 총 글자 수를 계산해줘."
result = agent.run(prompt)
print(result)

성공 판정

• 검색 결과 기반 요약 + 계산 결과가 함께 출력됨

3) 실행 및 검증

실행 명령

python mini_agent.py

검증 체크리스트

• 검색 근거가 텍스트에 반영됨
• 계산 결과(숫자)가 포함됨
• 답변이 한국어 요구사항과 일치함

4) 동작 흐름(아키텍처)

flowchart TD
    A[User Prompt] --> B[CodeAgent Planner]
    B --> C[DuckDuckGoSearchTool]
    B --> D[PythonInterpreterTool]
    C --> E[Evidence Snippets]
    D --> F[Computed Values]
    E --> G[Final Synthesis]
    F --> G
    G --> H[User Output]

5) 트러블슈팅 (3+)

1. ModuleNotFoundError: smolagents

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

2. 검색 도구 응답 지연/실패

   • 원인: 네트워크/일시적 차단
   • 해결: 재시도, VPN/프록시 점검, 프롬프트를 짧게 분할

3. 계산 코드 실행 오류(파이썬 인터프리터 툴)

   • 원인: LLM이 생성한 코드 문법 오류
   • 해결: 프롬프트에 “간단한 표준 파이썬만 사용” 명시

4. 결과가 장황하고 검증 불가

   • 원인: 출력 포맷 제약 부족
   • 해결: “JSON 형식으로 source/summary/count 반환” 요구

6) 확장 과제

• 과제 A: 출력 스키마를 JSON 고정 후 파서 검증 추가
• 과제 B: 검색 소스를 2개 이상 교차 검증
• 과제 C: 실패 시 재시도 로직(최대 2회) 추가

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 만들고, 실습 재현성(명령/입력/성공 기준)과 링크 유효성을 점검해 편집했습니다.