🤗 52. HF Agents Course 실습편 1 - Unit 1 요약 퀴즈 생성 에이전트 만들기

목표: Hugging Face Agents Course의 코스 구조, Unit 1의 Think → Act → Observe, smolagents의 CodeAgent/도구 개념을 바탕으로, 학습자가 바로 복습할 수 있는 요약 + 퀴즈 + 다음 액션 생성기를 재현한다.

공식 저장소는 코스를 기초 → 프레임워크 → 유스케이스 → 파이널 과제 흐름으로 소개한다. Unit 1 소개 페이지는 에이전트의 기본기, LLM의 역할, 도구와 액션, 그리고 Think → Act → Observe 워크플로를 먼저 익힌 뒤 첫 에이전트를 만들도록 설계되어 있다. smolagents 문서는 이런 입문 실험을 짧은 코드와 적은 추상화로 빠르게 시작할 수 있게 해 준다.

이번 실습은 이 세 가지를 묶어, 공식 페이지를 읽고 Unit 1 복습용 요약과 퀴즈를 자동 생성하는 미니 프로젝트를 만든다.

이번에 만들 결과물

입력 예시:

HF Agents Course Unit 1을 20분 안에 복습하고 싶어.
핵심 개념 4개와 객관식 퀴즈 3개, 다음 실습 1개를 한국어로 정리해줘.

출력 예시:

• Unit 1 핵심 개념 4개
• 객관식 퀴즈 3개
• 정답/해설
• 다음 실습 1개
• 실행 명령과 성공 판정

왜 이 실습이 코스 취지와 맞는가

• 공식 코스 소개는 이론 + 핸즈온 + 과제 조합으로 학습하도록 안내한다.
• Unit 1은 에이전트 기본 구조와 첫 에이전트 실습을 핵심 산출물로 둔다.
• smolagents와 Unit 2 smolagents 소개는 CodeAgent, ToolCallingAgent, Tools를 실제로 다뤄 보며 이해하라고 권한다.

즉 이 글의 포인트는 단순 요약이 아니라, 공식 자료를 도구로 읽고 결과를 학습 산출물로 재구성하는 에이전트 흐름을 직접 만드는 데 있다.

전체 구조

flowchart TD
    U[사용자 복습 요청] --> A[CodeAgent]
    A --> T1[get_course_overview]
    A --> T2[get_unit1_intro]
    A --> T3[get_smolagents_docs]
    A --> T4[get_smolagents_unit]
    T1 --> S[공식 근거 수집]
    T2 --> S
    T3 --> S
    T4 --> S
    S --> O[핵심 요약 + 퀴즈 3개 + 다음 실습 1개]

준비물

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

Step 1) 작업 폴더 준비

실행 명령

mkdir -p ~/hf-agents-quiz-agent
cd ~/hf-agents-quiz-agent

성공 판정

pwd
ls -la

• 현재 경로 끝이 hf-agents-quiz-agent이면 통과.
• 작업 폴더가 생성되면 통과.

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) 에이전트 코드 작성

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

import requests
from bs4 import BeautifulSoup
from smolagents import CodeAgent, InferenceClientModel, tool
 
PAGES = {
    "course": "https://huggingface.co/learn/agents-course",
    "unit1": "https://huggingface.co/learn/agents-course/en/unit1/introduction",
    "docs": "https://huggingface.co/docs/smolagents/index",
    "smol_unit": "https://huggingface.co/learn/agents-course/unit2/smolagents/introduction",
}
 
 
def fetch_text(url: str) -> str:
    response = requests.get(url, timeout=30)
    response.raise_for_status()
    soup = BeautifulSoup(response.text, "html.parser")
 
    chunks = []
    title = soup.title.get_text(" ", strip=True) if soup.title else url
    chunks.append(f"TITLE: {title}")
 
    for tag in soup.select("h1, h2, h3, p, li"):
        text = tag.get_text(" ", strip=True)
        if text and len(text) >= 24:
            chunks.append(text)
        if len(chunks) >= 40:
            break
 
    return "\n".join(chunks)
 
 
@tool
def get_course_overview() -> str:
    """Return a compact summary of the HF Agents Course overview page."""
    return fetch_text(PAGES["course"])
 
 
@tool
def get_unit1_intro() -> str:
    """Return a compact summary of the official Unit 1 introduction page."""
    return fetch_text(PAGES["unit1"])
 
 
@tool
def get_smolagents_docs() -> str:
    """Return a compact summary of the smolagents docs index."""
    return fetch_text(PAGES["docs"])
 
 
@tool
def get_smolagents_unit() -> str:
    """Return a compact summary of the course module introducing smolagents."""
    return fetch_text(PAGES["smol_unit"])
 
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[
        get_course_overview,
        get_unit1_intro,
        get_smolagents_docs,
        get_smolagents_unit,
    ],
    model=model,
    max_steps=6,
)
 
prompt = """
공식 페이지 도구 결과만 사용해서 한국어로 답해줘.
목표: HF Agents Course Unit 1 복습용 요약과 퀴즈를 만든다.
반드시 아래 형식을 지켜줘.
1) 핵심 개념 4개
2) 객관식 퀴즈 3개
3) 정답과 한 줄 해설
4) 다음 실습 1개
5) 실행 명령
6) 성공 판정 기준
공식 페이지에서 직접 확인되지 않는 내용은 반드시 '추정'이라고 표시해줘.
"""
 
result = agent.run(prompt)
print(result)

코드 확인 포인트

• @tool 데코레이터로 공식 페이지 읽기 함수를 도구로 노출했다.
• CodeAgent가 필요한 근거를 직접 수집한다.
• 출력 형식을 강하게 제한해, 학습 산출물이 흔들리지 않게 했다.

Step 4) 첫 실행

실행 명령

source .venv/bin/activate
python unit1_quiz_agent.py

성공 판정

아래 6가지를 만족하면 성공이다.

• 예외 없이 실행 완료
• 핵심 개념 4개 섹션 존재
• 객관식 퀴즈 3개 존재
• 정답과 한 줄 해설 존재
• 다음 실습 1개 존재
• 확인 불가 내용은 추정으로 표기

Step 5) 입력 프롬프트를 실습 중심으로 바꿔 재실행

입력 변경

prompt를 아래처럼 바꾼다.

나는 긴 설명보다 바로 손을 움직이고 싶다.
Unit 1 핵심을 10분 복습용으로 압축해서,
핵심 개념 3개와 퀴즈 2개, 다음 실행 명령 1세트를 정리해줘.

실행 명령

python unit1_quiz_agent.py

성공 판정

• Unit 1 관련 핵심 요약이 압축되어 나온다.
• 퀴즈 개수가 2개 또는 3개 수준으로 줄어든다.
• 실행 가능한 명령이 최소 1세트 제시된다.

Step 6) 결과를 Markdown 파일로 저장

실행 명령

python unit1_quiz_agent.py > latest-unit1-quiz.md
sed -n '1,120p' latest-unit1-quiz.md

성공 판정

• latest-unit1-quiz.md가 생성된다.
• 앞부분에 요약, 퀴즈, 정답, 다음 실습이 보인다.

이 실습에서 이해해야 할 핵심

1) Unit 1은 에이전트 사고 루프의 입구다

공식 Unit 1 소개는 에이전트의 정의, LLM의 역할, 도구, 액션, Think → Act → Observe를 먼저 다룬다. 따라서 첫 핸즈온은 복잡한 제품형 에이전트보다 작고 검증 가능한 학습 도우미가 더 적합하다.

2) smolagents는 입문 실험 속도가 빠르다

공식 문서는 CodeAgent를 중심으로, 적은 코드로 에이전트 실행과 도구 사용을 시작할 수 있다고 설명한다. 이번 프로젝트도 도구 4개 + 에이전트 1개 구조로 재현된다.

3) 공식 자료 기반 도구화가 품질을 높인다

그냥 LLM에게 “코스를 요약해줘”라고 묻는 것보다, 공식 페이지를 읽는 도구를 먼저 만들면 근거가 있는 출력을 얻기 쉽다. 이후 퀴즈, 플래너, 복습 코치 등으로 확장하기도 좋다.

실전 체크리스트

• 작업 폴더 생성 완료
• 가상환경 생성 및 활성화 완료
• smolagents, requests, beautifulsoup4 설치 완료
• unit1_quiz_agent.py 저장 완료
• 첫 실행 성공
• 프롬프트 변경 후 재실행 성공
• Markdown 저장 성공

트러블슈팅

1) ModuleNotFoundError: No module named 'smolagents'

원인:

• 가상환경 비활성 상태
• 다른 Python 인터프리터 사용

해결:

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

2) 401 Unauthorized 또는 Inference 인증 오류

원인:

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

해결:

export HF_TOKEN=hf_your_token
python unit1_quiz_agent.py

• 토큰 설정 후 재실행한다.
• 조직 네트워크 환경이면 별도 정책이 있을 수 있다.

3) requests.exceptions.ReadTimeout

원인:

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

해결:

response = requests.get(url, timeout=60)

• 타임아웃을 60초로 늘린다.
• 브라우저에서 URL이 열리는지 먼저 확인한다.

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

원인:

• 프롬프트 제약이 약함
• 도구 설명이 추상적임

해결:

• 핵심 개념, 퀴즈, 정답, 다음 실습, 실행 명령, 성공 판정을 명시한다.
• 공식 페이지 도구 결과만 사용 문구를 유지한다.
• 확인 불가 항목은 추정으로 강제한다.

5) HTML 추출 결과가 들쭉날쭉할 때

원인:

• 페이지마다 본문 DOM 구조 차이

해결:

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

• 선택자를 더 구체화한다.
• 필요하면 추출 결과를 파일로 저장해 비교한다.

6) 퀴즈 난이도가 지나치게 높거나 낮을 때

원인:

• 프롬프트에 대상 독자 수준이 없음

해결:

프롬프트에 아래 문구를 추가한다.

대상은 HF Agents Course를 처음 보는 입문자다.
전문 용어는 한 줄 설명과 함께 써줘.

확장 아이디어

• Unit 2용으로 CodeAgent와 ToolCallingAgent 비교 퀴즈 생성기 만들기
• 결과를 JSON으로 저장해 웹 UI나 노션으로 넘기기
• 사용자의 공부 시간(10분/20분/45분)에 따라 다른 퀴즈 난이도 내기
• save_report 도구를 추가해 자동 아카이빙하기

마무리

이번 핸즈온은 “에이전트를 만든다”보다 더 중요한 연습을 담고 있다. 공식 근거를 읽는 도구를 만들고, 그 도구 위에서 학습 산출물을 생성하게 하는 구조를 익히는 것이다. 이 패턴을 잡아두면 이후 Unit 2 프레임워크 비교, Unit 3 유스케이스 정리, 최종 프로젝트 리뷰에도 그대로 확장할 수 있다.

---

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 구조와 예시 코드를 작성했습니다. 다만 근거가 되는 설명은 Hugging Face Agents Course 저장소, HF Agents Course 공식 학습 페이지, Unit 1 소개 페이지, smolagents 공식 문서, smolagents 코스 소개 페이지를 기준으로 검토했고, 재현 단계·명령·성공 판정·트러블슈팅·링크 반영은 사람이 확인 가능한 형태로 정리했습니다.