🤗 01. HF Agents Course 본편 1 - smolagents 빠른 시작

왜 이걸 먼저 하나

HF Agents Course의 핵심은 **“LLM + 도구 + 실행 루프”**를 실제로 돌려보는 것이다. 1편에서는 가장 가볍게 smolagents로 재현한다.

오늘 실습 목표

• Python 환경 준비
• smolagents 설치
• 웹 검색 도구를 붙인 CodeAgent 1회 실행
• 성공/실패 판정 기준으로 재현 확인

전체 흐름

flowchart TD
  A[환경 준비] --> B[패키지 설치]
  B --> C[HF 토큰 설정]
  C --> D[CodeAgent + Tool 구성]
  D --> E[질문 실행]
  E --> F{성공 판정}
  F -->|Yes| G[결과 기록]
  F -->|No| H[오류 로그 점검 후 재실행]

사전 준비

도구

• Python 3.10+
• 터미널
• Hugging Face 계정 + Access Token

입력값

• HF_TOKEN: Hugging Face User Access Token
• 실습 질문: "Summarize today's top 3 AI agent news in Korean."

실습 단계

1) 작업 폴더와 가상환경 생성

mkdir -p hf-agents-ep01 && cd hf-agents-ep01
python -m venv .venv
source .venv/bin/activate
python -V

2) 패키지 설치

pip install -U smolagents duckduckgo-search litellm

3) 토큰 설정

export HF_TOKEN="여기에_토큰"

4) 실행 파일 작성 (run_ep01.py)

from smolagents import CodeAgent, DuckDuckGoSearchTool, HfApiModel
 
model = HfApiModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct")
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
    add_base_tools=True,
)
 
prompt = "Summarize today's top 3 AI agent news in Korean. Include source links."
result = agent.run(prompt)
print(result)

5) 실행

python run_ep01.py

성공 판정

아래 4개를 만족하면 성공:

1. 실행 중 tool call(검색) 흔적이 출력된다.
2. 한국어 요약이 3개 항목으로 나온다.
3. 각 항목에 출처 링크가 포함된다.
4. 에러 없이 프로세스가 종료된다(종료코드 0).

자주 막히는 지점

• 401/403: HF_TOKEN 누락 또는 권한 문제
• ModuleNotFoundError: 가상환경 미활성화
• 응답 지연: 모델 혼잡 시간대일 수 있으니 재시도

실무 적용 포인트

• 이 구조를 그대로 써서 매일 뉴스 요약 자동화의 최소 단위로 쓸 수 있다.
• 다음 편에서는 도구를 2~3개로 늘려, 검색 + 계산 + 포맷팅 체인으로 확장한다.

생성형 AI 활용 고지

이 문서는 생성형 AI(LLM)를 활용해 초안을 작성하고, 사람이 실습 가능성/정확성/구조를 검수해 정리했다.