🤗 55. HF Agents Course 실습편 1 - 코스 커리큘럼 브리핑 에이전트 만들기

목표: HF Agents Course의 코스 전체 구조, Unit 1의 기초 개념, smolagents의 빠른 시작 방식을 한 번에 읽어, 학습자에게 오늘 시작할 순서와 다음 실습을 제안하는 커리큘럼 브리핑 에이전트를 만든다.

Hugging Face Agents Course 저장소와 공식 학습 페이지는 코스를 기초(Unit 1) → 프레임워크(Unit 2) → 유스케이스(Unit 3) → 최종 과제(Unit 4) 흐름으로 안내한다. smolagents 문서는 이런 학습 실험을 적은 코드로 빠르게 재현할 수 있게 CodeAgent, ToolCallingAgent, 기본 도구 패턴을 제공한다. 이번 글은 그 둘을 연결해, 공식 자료를 읽고 오늘의 학습 우선순위를 정리하는 미니 프로젝트를 직접 만든다.

이번에 만들 결과물

입력 예시:

HF Agents Course를 이제 시작한다.
오늘 45분 안에 어디부터 봐야 하는지 한국어로 정리해줘.
필수 유닛, 바로 해볼 실습, 나중에 볼 심화 주제를 나눠줘.

출력 목표:

• 필수 유닛 3개
• 오늘 바로 할 실습 2개
• 나중에 볼 심화 주제 2개
• 실행 명령
• 성공 판정 기준

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

• 공식 저장소는 코스를 단계형 학습 여정으로 소개한다.
• 공식 학습 페이지는 이론, 핸즈온, 과제, 챌린지 구조를 강조한다.
• smolagents 공식 문서는 간단한 도구 조합으로 에이전트를 시작하는 방식을 제시한다.

즉 이번 실습은 단순 요약이 아니라, 공식 문서를 읽는 도구 + 결과를 행동 지침으로 재구성하는 에이전트 루프를 익히는 데 초점이 있다.

전체 구조

flowchart TD
    U[사용자 질문] --> A[CodeAgent]
    A --> T1[get_course_repo]
    A --> T2[get_course_overview]
    A --> T3[get_smolagents_intro]
    T1 --> S[공식 근거 수집]
    T2 --> S
    T3 --> S
    S --> R[필수 유닛/오늘의 실습/심화 주제 브리핑]

준비물

• Python 3.10+
• 터미널
• 인터넷 연결
• Hugging Face 계정 권장
• 필요 시 HF_TOKEN 환경변수

Step 1) 작업 폴더 준비

도구

• 터미널

입력

mkdir -p ~/hf-agents-course-briefing
cd ~/hf-agents-course-briefing

실행 명령

pwd
ls -la

성공 판정

• 현재 경로 끝이 hf-agents-course-briefing이면 통과.
• 빈 작업 폴더가 보이면 통과.

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

파일명: course_briefing_agent.py

import requests
from bs4 import BeautifulSoup
from smolagents import CodeAgent, InferenceClientModel, tool
 
PAGES = {
    "repo": "https://github.com/huggingface/agents-course",
    "course": "https://huggingface.co/learn/agents-course",
    "docs": "https://huggingface.co/docs/smolagents/index",
}
 
 
def fetch_compact_text(url: str) -> str:
    response = requests.get(url, timeout=30)
    response.raise_for_status()
    soup = BeautifulSoup(response.text, "html.parser")
 
    blocks = []
    title = soup.title.get_text(" ", strip=True) if soup.title else url
    blocks.append(f"TITLE: {title}")
 
    for tag in soup.select("h1, h2, h3, p, li"):
        text = tag.get_text(" ", strip=True)
        if len(text) >= 30:
            blocks.append(text)
        if len(blocks) >= 50:
            break
 
    return "\n".join(blocks)
 
 
@tool
def get_course_repo() -> str:
    """Return a compact summary of the Hugging Face Agents Course repository page."""
    return fetch_compact_text(PAGES["repo"])
 
 
@tool
def get_course_overview() -> str:
    """Return a compact summary of the Hugging Face Agents Course overview page."""
    return fetch_compact_text(PAGES["course"])
 
 
@tool
def get_smolagents_intro() -> str:
    """Return a compact summary of the smolagents documentation homepage."""
    return fetch_compact_text(PAGES["docs"])
 
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[get_course_repo, get_course_overview, get_smolagents_intro],
    model=model,
    max_steps=6,
)
 
prompt = """
공식 도구 결과만 근거로 한국어로 답해줘.
아래 형식을 반드시 지켜줘.
1) 필수 유닛 3개
2) 오늘 바로 할 실습 2개
3) 나중에 볼 심화 주제 2개
4) 왜 이 순서가 좋은지 3문장
5) 실행 명령 1세트
6) 성공 판정 기준 3개
공식 자료에서 직접 확인되지 않는 내용은 '추정'이라고 표시해.
사용자 상황: HF Agents Course를 처음 시작하며 오늘 45분 투자 가능.
"""
 
result = agent.run(prompt)
print(result)

Step 4) 첫 실행

도구

• 터미널

실행 명령

source .venv/bin/activate
python course_briefing_agent.py

성공 판정

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

• 예외 없이 실행 완료
• 필수 유닛 3개 섹션 존재
• 오늘 바로 할 실습 2개 섹션 존재
• 나중에 볼 심화 주제 2개 섹션 존재
• 실행 명령 1세트가 포함됨
• 불확실한 내용은 추정으로 표시됨

Step 5) 다른 사용자 상황으로 재실행

입력 변경

prompt의 마지막 사용자 상황을 아래처럼 바꾼다.

사용자 상황: Unit 1은 이미 읽었고, 이번 주말에 Unit 2 프레임워크 비교만 빠르게 훑고 싶다. 오늘 30분 투자 가능.

실행 명령

python course_briefing_agent.py

성공 판정

• Unit 2 또는 프레임워크 학습이 우선순위로 올라오면 성공.
• 오늘 할 일과 나중에 볼 심화 주제가 분리되어 나오면 성공.

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

실행 명령

python course_briefing_agent.py > latest-course-briefing.md
sed -n '1,120p' latest-course-briefing.md

성공 판정

• latest-course-briefing.md 파일이 생성된다.
• 앞부분에 필수 유닛, 오늘 실습, 심화 주제가 보인다.

코드 이해 포인트

1) 공식 페이지를 먼저 도구화한다

무턱대고 답변을 생성하기보다, 저장소/코스 소개/docs를 먼저 읽게 하면 근거가 더 분명해진다.

2) CodeAgent가 정리 역할을 맡는다

도구가 원문을 수집하고, 에이전트는 그 근거를 사용자 상황에 맞게 압축한다.

3) 출력 형식을 강하게 고정한다

입문용 핸즈온에서는 자유도보다 재현성이 더 중요하다. 섹션 수를 고정하면 결과 검증이 쉬워진다.

실전 체크리스트

• 작업 폴더 생성 완료
• 가상환경 생성 및 활성화 완료
• 패키지 설치 완료
• course_briefing_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 호출에 인증이 필요한 환경

해결:

export HF_TOKEN=hf_your_token
python course_briefing_agent.py

3) requests.exceptions.ReadTimeout

원인:

• 네트워크 지연
• 페이지 응답 속도 저하

해결:

response = requests.get(url, timeout=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"):

• 선택자를 더 구체화한다.
• 중간 추출 결과를 파일로 저장해 점검한다.

확장 아이디어

• Unit 2 전용 브리핑 모드 추가
• 결과를 JSON으로 저장해 대시보드에 연결
• ToolCallingAgent 버전으로 바꿔 출력 차이 비교
• 사용자의 학습 시간에 따라 10분/30분/60분 플랜 자동 분기

마무리

이번 미니 프로젝트의 핵심은 화려한 기능이 아니라 공식 자료를 읽는 도구를 만들고, 그 도구 위에 학습 우선순위 브리핑을 얹는 구조를 익히는 데 있다. 이 패턴을 잡아두면 다음에는 Unit 2 프레임워크 비교, Unit 3 유스케이스 정리, 최종 과제 준비 가이드까지 같은 방식으로 확장할 수 있다.

---

생성형 AI 활용 고지

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