🤗 49. HF Agents Course 실습편 1 - Alfred 스타일 학습 도우미 에이전트 핸즈온

목표: Hugging Face Agents Course의 공식 코스 구조(Unit 0~4), Unit 1의 Think → Act → Observe 흐름, smolagents의 CodeAgent 빠른 시작을 한 번에 손으로 확인하는 미니 프로젝트를 재현한다.

Hugging Face Agents Course 저장소는 코스를 4개 유닛 + 보너스 유닛으로 설명하고, Unit 1은 에이전트의 기본 개념과 도구 사용, Think → Act → Observe 워크플로를 다룬다. 또 smolagents 문서는 몇 줄 코드로 CodeAgent를 시작할 수 있는 경량 라이브러리라는 점을 강조한다. 이번 실습은 이 세 가지를 묶어, 공식 자료를 읽고 오늘의 학습 계획과 실습 명령을 제안하는 CLI 에이전트를 만든다.

이번에 만들 결과물

입력 예시:

나는 오늘 45분만 쓸 수 있어. HF Agents Course를 처음 시작하는 사람 기준으로
무엇을 읽고 어떤 실습을 먼저 돌리면 좋은지 알려줘.

출력 예시:

• 3줄 요약
• 추천 학습 순서
• 오늘 바로 할 실습 1개
• 실행 명령
• 성공 판정 기준

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

• 공식 저장소는 코스를 onboarding → fundamentals → frameworks → use cases → final assignment 흐름으로 설명한다.
• Unit 1 소개 페이지는 에이전트 기초, 도구, LLM 역할, Think → Act → Observe를 먼저 익히고 이후 첫 에이전트 Alfred를 만든다고 안내한다.
• smolagents 문서는 CodeAgent + 최소 도구 구성으로 빠르게 실험하는 패턴을 제시한다.

즉 이번 실습은 “이론만 읽기”가 아니라, 공식 자료를 읽는 도구와 그 도구를 쓰는 에이전트를 함께 만드는 입문용 핸즈온이다.

전체 구조

flowchart TD
    U[사용자 질문] --> A[CodeAgent]
    A --> T1[get_course_map]
    A --> T2[get_unit1_focus]
    A --> T3[get_smolagents_quickstart]
    T1 --> S[공식 정보 요약]
    T2 --> S
    T3 --> S
    S --> O[오늘의 학습 순서 + 실행 명령 + 성공 판정]

준비물

• 도구
  • Python 3.10+
  • 터미널
  • 인터넷 연결
• 입력
  • Hugging Face 계정 권장
  • 선택: HF_TOKEN 환경변수
• 참고 공식 링크
  • agents-course 저장소
  • HF Agents Course 학습 페이지
  • smolagents 문서

Step 1) 작업 폴더 준비

입력

mkdir -p ~/hf-agents-handson-alfred
cd ~/hf-agents-handson-alfred

성공 판정

pwd
ls -la

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

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

alfred_study_coach.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",
    "smolagents": "https://huggingface.co/docs/smolagents/index",
    "repo": "https://github.com/huggingface/agents-course",
}
 
 
def fetch_text(url: str) -> str:
    response = requests.get(url, timeout=30)
    response.raise_for_status()
    soup = BeautifulSoup(response.text, "html.parser")
 
    parts = []
    title = soup.title.get_text(" ", strip=True) if soup.title else url
    parts.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) >= 20:
            parts.append(text)
        if len(parts) >= 35:
            break
 
    return "\n".join(parts)
 
 
@tool
def get_course_map() -> str:
    """Return a compact summary of the official HF Agents Course overview page."""
    return fetch_text(PAGES["course"])
 
 
@tool
def get_unit1_focus() -> str:
    """Return a compact summary of the official Unit 1 introduction page."""
    return fetch_text(PAGES["unit1"])
 
 
@tool
def get_smolagents_quickstart() -> str:
    """Return a compact summary of the official smolagents docs index page."""
    return fetch_text(PAGES["smolagents"])
 
 
@tool
def get_repo_outline() -> str:
    """Return a compact summary of the official agents-course repository page."""
    return fetch_text(PAGES["repo"])
 
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[
        get_course_map,
        get_unit1_focus,
        get_smolagents_quickstart,
        get_repo_outline,
    ],
    model=model,
    max_steps=6,
)
 
prompt = """
공식 페이지 도구 결과만 사용해 한국어로 답해줘.
질문: 나는 오늘 45분만 쓸 수 있어. HF Agents Course를 처음 시작하는 사람 기준으로
1) 3줄 요약
2) 추천 학습 순서(3단계)
3) 오늘 바로 실행할 실습 1개
4) 실행 명령
5) 성공 판정 기준
형식으로 정리해줘.
공식 페이지에서 직접 확인되지 않는 내용은 반드시 '추정'이라고 표시해줘.
"""
 
result = agent.run(prompt)
print(result)

코드 확인 포인트

• @tool로 공식 페이지 읽기 함수를 도구화했다.
• CodeAgent가 도구를 호출해 스스로 필요한 정보를 모은다.
• 답변 범위를 공식 자료로 제한해 근거가 흔들리지 않게 했다.

Step 4) 첫 실행

실행 명령

source .venv/bin/activate
python alfred_study_coach.py

성공 판정

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

• 실행이 예외 없이 끝난다.
• 출력에 3줄 요약이 있다.
• 추천 학습 순서가 3단계로 정리된다.
• 오늘 바로 실행할 실습 1개가 분리되어 있다.
• 확인 불가 내용이 있으면 추정 표기가 들어간다.

Step 5) 질문을 바꿔 재실행

이번에는 실습 중심 입력으로 바꾼다.

입력

prompt를 아래로 바꾼다.

나는 긴 이론보다 먼저 손을 움직이고 싶어.
Unit 1 핵심만 빠르게 훑고 smolagents를 써보는 가장 짧은 경로를
2단계 학습 순서와 1개 실습 명령으로 정리해줘.

실행 명령

python alfred_study_coach.py

성공 판정

• Unit 1과 smolagents가 모두 언급된다.
• 학습 순서가 2단계 또는 3단계로 압축된다.
• 실제 실행 가능한 명령이 1세트 이상 제시된다.

Step 6) 출력 저장

실행 명령

python alfred_study_coach.py > latest-study-plan.md
sed -n '1,80p' latest-study-plan.md

성공 판정

• latest-study-plan.md 파일이 생성된다.
• 첫 80줄 안에 요약, 순서, 실습 항목이 보인다.

이 실습에서 꼭 이해할 개념

1) 코스 구조를 먼저 잡아야 길을 잃지 않는다

공식 코스 소개는 학습 흐름을 기초 개념 → 프레임워크 → 유스케이스 → 파이널 과제로 제시한다. 초반에는 모든 유닛을 다 읽기보다, 내가 지금 어디에 있는지 먼저 파악하는 것이 중요하다.

2) Unit 1은 에이전트 사고 루프의 출발점이다

Unit 1 소개 페이지는 에이전트 정의, LLM의 역할, 도구, 액션, Think → Act → Observe 루프를 다룬 뒤 Alfred를 만든다고 안내한다. 그래서 첫 실습도 복잡한 멀티에이전트보다 작은 도구 + 단일 에이전트 조합이 적합하다.

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

smolagents 문서는 CodeAgent를 매우 짧은 코드로 시작할 수 있다고 설명한다. 이번 프로젝트도 복잡한 프레임워크 설정 없이 도구 4개 + CodeAgent 1개로 끝난다.

실전 점검 체크리스트

• Python 가상환경 생성 완료
• smolagents, requests, beautifulsoup4 설치 완료
• alfred_study_coach.py 저장 완료
• 첫 실행 성공
• 질문 변경 후 재실행 성공
• 결과 파일 저장 성공

트러블슈팅

1) ModuleNotFoundError: No module named 'smolagents'

원인:

• 가상환경이 꺼져 있음
• 다른 Python 인터프리터로 실행함

해결:

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

2) 401 Unauthorized 또는 모델 인증 오류

원인:

• 실행 환경에서 Hugging Face Inference 인증이 요구됨

해결:

export HF_TOKEN=hf_your_token
python alfred_study_coach.py

• 토큰 설정 후 다시 실행한다.
• 조직 환경이면 사내 프록시 또는 정책 때문에 별도 인증이 필요할 수 있다.

3) requests.exceptions.ReadTimeout

원인:

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

해결:

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

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

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

원인:

• 프롬프트 형식 제약이 약함
• 도구 설명이 너무 모호함

해결:

• 프롬프트에 3줄 요약, 추천 학습 순서, 실행 명령, 성공 판정 기준을 명시한다.
• 공식 페이지 도구 결과만 사용 문구를 유지한다.
• 확인 불가 정보는 추정 표기를 강제한다.

5) GitHub 저장소 내용이 기대보다 빈약하게 잡힐 때

원인:

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

해결:

• 저장소 페이지는 전체 코스 구조 확인용으로만 쓴다.
• 세부 설명은 course, unit1, smolagents 비중을 높인다.
• 필요하면 README raw URL을 별도 도구로 읽도록 확장한다.

6) HTML 추출 품질이 들쭉날쭉할 때

원인:

• 페이지마다 h1, p, li 배치 구조가 다름

해결:

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

• 선택자를 더 구체화한다.
• 추출 결과를 파일로 저장해 어떤 태그가 잘 잡히는지 먼저 본다.

확장 아이디어

• unit2, unit3, unit4 전용 도구를 추가해 중급 학습 코치로 확장하기
• 사용자 입력 시간을 20분/45분/90분으로 받아 다른 학습 계획을 내놓기
• 결과를 Markdown 템플릿으로 저장하는 save_markdown_report 도구 추가하기
• ToolCallingAgent 버전으로 바꿔 CodeAgent와 응답 차이 비교하기

마무리

이번 핸즈온의 핵심은 에이전트를 거창하게 만드는 데 있지 않다. 공식 자료를 읽는 도구를 먼저 만들고, 그 위에서 에이전트가 학습 결정을 내리게 하는 구조를 익히는 데 있다. 이 구조를 잡아두면 이후 Unit 2의 프레임워크 비교나 최종 프로젝트에서도 근거 중심으로 확장하기가 훨씬 쉬워진다.

---

생성형 AI 활용 고지

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