🤗 46. HF Agents Course 실습편 1 - smolagents로 코스 로드맵 CLI 만들기

목표: Hugging Face Agents Course 공식 자료와 smolagents만 써서 코스 로드맵을 설명하고 바로 오늘 할 과제까지 제안하는 CLI 미니 프로젝트를 재현한다.

이번 실습은 HF Agents Course가 강조하는 두 축을 바로 손으로 확인하는 데 맞춘다.

• 코스는 기초 이론 → 프레임워크 → 유스케이스 → 최종 과제 흐름으로 구성된다.
• smolagents는 작은 코드로 에이전트와 도구를 빠르게 붙여보는 출발점으로 적합하다.

즉, 이번 글은 “문서를 읽고 끝”이 아니라 공식 코스 소개 페이지를 읽는 도구를 만들고, 그 도구를 쓰는 에이전트까지 연결하는 첫 실습편이다.

무엇을 만들까

입력:

• 나는 하루 40분만 투자할 수 있어. Unit 0, Unit 1, smolagents 중 무엇부터 보고 오늘 바로 어떤 예제를 실행하면 좋을까?

출력:

• 코스 3줄 요약
• 추천 학습 순서
• 각 페이지를 왜 먼저 봐야 하는지 설명
• 오늘 바로 실행할 명령 1세트
• 시작 전 체크리스트

이 실습이 좋은 이유

• 정보원을 GitHub 저장소 / 공식 코스 / smolagents 문서로 제한해 답변 근거가 흔들리지 않는다.
• @tool + CodeAgent 조합을 가장 작게 경험할 수 있다.
• 결과물이 단순 데모가 아니라 개인 학습 코치 CLI라서 재사용 가치가 높다.

전체 흐름

flowchart TD
    Q[사용자 질문] --> A[CodeAgent]
    A --> T[get_official_section 툴]
    T --> C[공식 코스 페이지 읽기]
    C --> S[섹션별 핵심 정보 압축]
    S --> R[학습 순서 + 오늘의 실습 제안]

준비물

• Python 3.10+
• 터미널
• 인터넷 연결
• Hugging Face 계정 권장
• 선택: HF_TOKEN 환경변수

Step 1) 작업 폴더 생성

입력

mkdir -p ~/hf-agents-course-handson-01
cd ~/hf-agents-course-handson-01

성공 판정

pwd

• 출력 끝이 hf-agents-course-handson-01 이면 통과.

Step 2) 가상환경과 패키지 설치

입력

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install "smolagents[toolkit]" requests beautifulsoup4

성공 판정

python -c "import smolagents, requests, bs4; print('install-ok')"

• install-ok가 출력되면 통과.

Step 3) CLI 코드 작성

roadmap_cli.py 파일을 만들고 아래 코드를 넣는다.

import requests
from bs4 import BeautifulSoup
from smolagents import CodeAgent, InferenceClientModel, tool
 
OFFICIAL_PAGES = {
    "repo": "https://github.com/huggingface/agents-course",
    "unit0": "https://huggingface.co/learn/agents-course/en/unit0/introduction",
    "unit1": "https://huggingface.co/learn/agents-course/en/unit1/introduction",
    "smolagents": "https://huggingface.co/docs/smolagents/index",
}
 
@tool
def get_official_section(name: str) -> str:
    """Read one official HF Agents Course related page and return a compact summary.
 
    Args:
        name: One of repo, unit0, unit1, smolagents.
    """
    key = name.strip().lower()
    if key not in OFFICIAL_PAGES:
        return f"Unknown page: {key}. Choose from: {', '.join(OFFICIAL_PAGES)}"
 
    response = requests.get(OFFICIAL_PAGES[key], timeout=30)
    response.raise_for_status()
 
    soup = BeautifulSoup(response.text, "html.parser")
    title = soup.title.get_text(" ", strip=True) if soup.title else key
 
    headings = []
    for tag in soup.select("h1, h2, h3"):
        text = tag.get_text(" ", strip=True)
        if text and text not in headings:
            headings.append(text)
        if len(headings) >= 8:
            break
 
    snippets = []
    for tag in soup.select("p, li"):
        text = tag.get_text(" ", strip=True)
        if len(text) >= 40 and text not in snippets:
            snippets.append(text)
        if len(snippets) >= 8:
            break
 
    return (
        f"PAGE: {key}\n"
        f"URL: {OFFICIAL_PAGES[key]}\n"
        f"TITLE: {title}\n"
        f"HEADINGS:\n- " + "\n- ".join(headings) + "\n\n"
        f"SNIPPETS:\n- " + "\n- ".join(snippets)
    )
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[get_official_section],
    model=model,
    max_steps=6,
)
 
prompt = """
공식 페이지 정보만 사용해서 한국어로 답해줘.
질문: 나는 하루 40분만 투자할 수 있어. HF Agents Course를 처음 시작하는 사람 기준으로
repo, unit0, unit1, smolagents를 참고해
1) 3줄 요약
2) 추천 학습 순서
3) 오늘 바로 실행할 실습 1개
4) 시작 전 체크리스트 4개
형식으로 답해줘.
공식 페이지에서 직접 확인되지 않는 내용은 '추정'이라고 표시해줘.
"""
 
result = agent.run(prompt)
print(result)

Step 4) 첫 실행

실행 명령

python roadmap_cli.py

성공 판정

아래 5개를 만족하면 성공이다.

• 실행이 중간 예외 없이 끝난다.
• 출력 맨 위에 3줄 요약이 있다.
• 추천 학습 순서가 번호 목록으로 나온다.
• 오늘 바로 실행할 실습 1개에 실제 명령 또는 코드 실행 제안이 있다.
• 공식 확인이 어려운 내용은 추정으로 표시된다.

Step 5) 질문을 바꿔 다시 검증

같은 파일에서 prompt만 아래처럼 바꾸고 재실행한다.

입력

나는 이론을 길게 읽기보다 빨리 손을 움직이고 싶어.
Unit 1을 최소한으로 보고 smolagents로 넘어가는 가장 짧은 학습 경로와
지금 당장 실행할 코드 1개만 추천해줘.

실행 명령

python roadmap_cli.py

성공 판정

• smolagents가 우선순위에 포함된다.
• 경로가 2~3단계 정도로 압축된다.
• 실행할 코드 1개가 분리돼 제시된다.

Step 6) 결과를 파일로 저장해 재사용성 확인

실습 결과를 매번 복붙하지 않도록 저장 리다이렉션까지 붙인다.

실행 명령

python roadmap_cli.py > latest-roadmap.md

성공 판정

ls -lh latest-roadmap.md
sed -n '1,40p' latest-roadmap.md

• 파일이 생성된다.
• 첫 40줄 안에 요약/추천 순서/실습 항목이 보인다.

코드에서 꼭 확인할 포인트

1) 공식 정보원 제한

OFFICIAL_PAGES를 고정해두면, 에이전트가 임의 블로그나 검색 결과로 새지 않고 공식 자료만 근거로 삼게 된다.

2) CodeAgent의 빠른 실험성

smolagents 문서는 CodeAgent를 매우 적은 코드로 시작할 수 있는 장점으로 소개한다. 이번 실습은 그 장점을 학습 코치 CLI로 바로 체감하게 만든다.

3) 코스 구조와 실습 연결

공식 코스 소개는 이론만이 아니라 핸즈온과 과제 수행 흐름을 강조한다. 그래서 출력 형식도 요약으로 끝내지 않고 “오늘 바로 할 실습”을 필수로 둔다.

실전 체크리스트

• 가상환경 활성화
• smolagents, requests, beautifulsoup4 설치 확인
• roadmap_cli.py 저장 완료
• 첫 실행 성공
• 질문 변경 후 재실행 성공
• latest-roadmap.md 저장 성공

트러블슈팅

1) ModuleNotFoundError: No module named 'smolagents'

원인:

• 다른 파이썬 인터프리터로 실행함
• 가상환경이 비활성화됨

해결:

source .venv/bin/activate
which python
python -m pip install "smolagents[toolkit]"

2) requests.exceptions.ReadTimeout

원인:

• 네트워크 지연
• 공식 페이지 응답 지연

해결:

response = requests.get(OFFICIAL_PAGES[key], timeout=60)

• timeout을 늘린다.
• 브라우저에서 URL이 열리는지 먼저 확인한다.

3) 401 또는 모델 인증 오류

원인:

• 실행 환경에서 Hugging Face Inference 인증이 필요함

해결:

export HF_TOKEN=hf_xxx_your_token
python roadmap_cli.py

• 토큰 설정 후 다시 실행한다.

4) 출력이 너무 일반론적일 때

원인:

• 프롬프트에서 공식 페이지 이름을 명시하지 않음
• 출력 형식 제약이 약함

해결:

• repo, unit0, unit1, smolagents를 참고해 문장을 유지한다.
• 출력 형식을 번호 목록으로 고정한다.
• 확인 불가 내용은 추정 표기를 강제한다.

5) 본문 추출이 빈약할 때

원인:

• 페이지 마크업 구조가 달라 p, li 선택이 충분치 않음

해결:

for tag in soup.select("main p, main li, article p, article li, h2, h3"):

• 선택자를 더 구체화한다.
• 필요하면 response.text[:2000]를 저장해 HTML 구조를 직접 확인한다.

6) GitHub 저장소 페이지에서 내용이 기대보다 짧게 잡힐 때

원인:

• GitHub HTML 구조 특성상 본문 추출이 제한될 수 있음

해결:

• 저장소는 전체 코스 구조 확인용으로만 쓰고,
• 실제 세부 설명은 unit0, unit1, smolagents 페이지 비중을 높여 프롬프트를 조정한다.

확장 아이디어

• unit2, unit3, unit4를 추가해 중급 학습 경로 추천기로 확장하기
• 응답을 Markdown 템플릿으로 저장하는 save_report 툴 추가하기
• DuckDuckGoSearchTool()을 붙여 공식 자료와 커뮤니티 자료를 분리 비교하기
• 사용자 가용 시간(20분/40분/90분)에 따라 다른 학습 경로를 내놓게 만들기

마무리

이번 실습의 핵심은 에이전트에게 “똑똑하게 답하라”라고만 말하는 것이 아니다. 공식 자료를 읽는 도구를 먼저 만들고, 그 도구 위에서 답하게 하는 구조를 만드는 것이 핵심이다. 이 한 번의 습관이 이후 Unit 2 프레임워크 실습과 최종 프로젝트 품질을 크게 좌우한다.

---

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 구조와 예시 코드를 작성했고, 공개된 Hugging Face Agents Course 저장소·공식 코스 페이지·smolagents 문서를 기준으로 사람이 재현 단계, 명령, 성공 판정, 트러블슈팅, 링크 반영 여부를 검토해 편집했습니다.