🤗 36. HF Agents Course 본편 1 - 첫 smolagents 에이전트 만들기

목표: 처음 접하는 사람도 15~20분 안에 smolagents로 실행 가능한 에이전트를 만들고, 도구(웹 검색)까지 붙여 본다.

1) 왜 이걸 먼저 하나?

HF Agents Course의 핵심 흐름은 생각(Thought) → 행동(Action) → 관찰(Observation) 루프를 실제로 다뤄보는 것입니다.
첫 편에서는 가장 가벼운 smolagents로 루프를 바로 체험합니다.

2) 전체 흐름 (Mermaid)

flowchart LR
    A[사용자 질문 입력] --> B[CodeAgent]
    B --> C{도구 필요?}
    C -- 아니오 --> D[내부 추론 후 답변]
    C -- 예 --> E[DuckDuckGoSearchTool 실행]
    E --> F[검색 결과 관찰]
    F --> B
    D --> G[최종 답변 출력]

3) 실습 준비

도구

• Python 3.10+
• 가상환경(venv)
• 터미널

입력(실습 질문)

• "2026년에 공개된 Hugging Face Agents Course의 핵심 목표 3가지를 한글로 요약해줘"

실행 명령

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

성공 판정

• 설치 에러 없이 프롬프트가 복귀한다.
• python -c "import smolagents; print('ok')" 실행 시 ok 출력.

4) 최소 에이전트 코드 작성

app.py:

from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool
 
model = InferenceClientModel()  # HF Inference 기반 기본 모델 사용
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
)
 
query = "2026년에 공개된 Hugging Face Agents Course의 핵심 목표 3가지를 한글로 요약해줘"
result = agent.run(query)
print(result)

5) 실행

python app.py

성공 판정

• 에이전트가 검색 도구를 호출한 뒤 최종 답변을 출력한다.
• 답변에 최소 3개 항목 요약이 포함된다.

6) 초보자 체크포인트 (막히는 지점 빠르게 해결)

1. ImportError 발생
   → 가상환경 활성화(source .venv/bin/activate) 확인
2. 모델 호출/권한 에러
   → HF 토큰 설정 확인 (export HF_TOKEN=...)
3. 검색 결과 품질이 낮음
   → 질문을 좁혀서 재질문 (예: “Unit 1 중심으로”)

7) 실무 적용 포인트

• 리서치 초안 자동화: 사람이 하던 1차 자료 탐색을 에이전트가 먼저 수행.
• 반복 업무 표준화: 같은 프롬프트 템플릿으로 매일 같은 형식 결과 생산.
• 검증 루프 추가 용이: 다음 편에서 평가/로그를 붙이면 품질 관리까지 확장 가능.

8) 다음 편 예고

다음 본편에서는 도구를 2개 이상 연결하고, 실패 시 재시도 규칙(간단 가드레일)을 넣어 실무형 에이전트로 확장합니다.

---

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 구조와 예시 코드를 만들고, 작성자가 실습 재현성·링크 정확성·문장 표현을 검토해 편집했습니다.