🤗 43. HF Agents Course 실습편 2 - 공식 코스 탐색 Q&A 에이전트 만들기

목표: Hugging Face Agents Course 공식 페이지를 직접 읽는 smolagents 기반 Q&A 에이전트를 만들어, 코스 구조를 묻고 요약하고 다음 학습 행동까지 제안하는 미니 프로젝트를 재현한다.

이번 실습은 “공식 문서 읽기 → 필요한 구간만 추출 → 한국어로 재구성” 흐름을 손에 익히는 데 초점을 둔다. Hugging Face Agents Course 소개 페이지가 말하는 핵심 축은 이렇다.

• 과정은 기초 개념, 핸즈온, 유스케이스, 최종 과제로 이어진다.
• Unit 2에서는 smolagents, LangGraph, LlamaIndex 같은 프레임워크를 다룬다.
• 권장 학습 속도는 주당 3~4시간, 각 챕터 1주 수준이다.

무엇을 만들까

사용자 입력 예시:

• HF Agents Course를 처음 시작하는데, Unit 0/1/2.1을 어떤 순서로 읽어야 하고 바로 해볼 실습은 뭐야?

에이전트 출력 예시:

• 코스 구조 3줄 요약
• 추천 학습 순서
• 각 Unit에서 확인할 핵심 포인트
• 바로 실행할 실습 1개
• 주의할 전제조건

왜 이 실습이 좋은가

• 검색 결과를 두루뭉술하게 섞지 않고 공식 코스 URL만 읽도록 제한한다.
• CodeAgent와 커스텀 툴을 함께 써서, “도구를 가진 에이전트”의 구조를 가장 작게 경험할 수 있다.
• 결과물이 단순 요약이 아니라 다음 행동이 바로 나오는 학습 Q&A 도우미다.

전체 흐름

flowchart TD
    U[사용자 질문] --> A[CodeAgent]
    A --> T[get_course_section 툴 호출]
    T --> P[공식 HF Agents Course 페이지 수집/정리]
    P --> S[섹션별 핵심 정보 추출]
    S --> R[학습 순서 + 실습 제안 한국어 답변]

준비물

• Python 3.10+
• 터미널
• 인터넷 연결
• 가상환경(venv)
• 선택: Hugging Face 토큰 (HF_TOKEN)

Step 1) 작업 폴더 만들기

입력

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

성공 판정

• pwd 결과가 ~/hf-agents-course-lab02 이다.

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('ok')"

• ok가 출력되면 통과.

Step 3) 실습 코드 작성

app.py를 만들고 아래 코드를 넣는다.

import requests
from bs4 import BeautifulSoup
from smolagents import CodeAgent, InferenceClientModel, tool
 
COURSE_PAGES = {
    "unit0": "https://huggingface.co/learn/agents-course/en/unit0/introduction",
    "unit1": "https://huggingface.co/learn/agents-course/en/unit1/introduction",
    "unit2": "https://huggingface.co/learn/agents-course/en/unit2/introduction",
    "smolagents": "https://huggingface.co/learn/agents-course/en/unit2/smolagents/introduction",
}
 
@tool
def get_course_section(section: str) -> str:
    """Return a compact summary of an official HF Agents Course section.
 
    Args:
        section: One of unit0, unit1, unit2, smolagents.
    """
    section = section.strip().lower()
    if section not in COURSE_PAGES:
        return f"Unknown section: {section}. Choose from {', '.join(COURSE_PAGES)}"
 
    response = requests.get(COURSE_PAGES[section], timeout=20)
    response.raise_for_status()
 
    soup = BeautifulSoup(response.text, "html.parser")
    title = soup.title.get_text(" ", strip=True) if soup.title else section
 
    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
 
    paragraphs = []
    for tag in soup.select("p, li"):
        text = tag.get_text(" ", strip=True)
        if len(text) >= 40:
            paragraphs.append(text)
        if len(paragraphs) >= 8:
            break
 
    return (
        f"SECTION: {section}\n"
        f"URL: {COURSE_PAGES[section]}\n"
        f"TITLE: {title}\n"
        f"HEADINGS:\n- " + "\n- ".join(headings) + "\n\n"
        f"KEY_TEXT:\n- " + "\n- ".join(paragraphs)
    )
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[get_course_section],
    model=model,
    max_steps=6,
)
 
prompt = """
공식 HF Agents Course 정보만 사용해서 한국어로 답해줘.
질문: HF Agents Course를 처음 시작하는데, unit0 / unit1 / smolagents 섹션을 어떤 순서로 읽어야 하고,
각 섹션에서 무엇을 얻는지 설명한 뒤, 오늘 바로 해볼 실습 1개를 제안해줘.
출력 형식:
1) 3줄 요약
2) 추천 순서 (번호 목록)
3) 섹션별 핵심 포인트
4) 오늘 바로 할 실습 1개
5) 시작 전 체크사항 3개
공식 페이지에서 확인되지 않는 내용은 추정이라고 표시해줘.
"""
 
result = agent.run(prompt)
print(result)

Step 4) 실행

실행 명령

python app.py

성공 판정

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

• 실행이 에러 없이 끝난다.
• 출력 맨 앞에 3줄 요약이 있다.
• 추천 순서에 최소 3개 항목이 있다.
• 오늘 바로 할 실습 1개가 따로 제시된다.
• 공식 페이지에 없는 정보는 추정 여부가 표시된다.

Step 5) 질문을 바꿔 재검증

같은 코드에서 prompt를 아래처럼 바꿔 다시 실행한다.

검증 입력

감사 목적이 아니라 빠른 실습 목적이야.
Unit 1 이론을 최소한으로 보고 smolagents로 바로 넘어가려는 사람 기준으로,
지금 꼭 읽을 페이지 2개와 바로 실행할 코드 1개만 추천해줘.

성공 판정

• 페이지 추천 수가 정확히 2개로 줄어든다.
• smolagents 섹션이 우선순위에 반영된다.
• 실행 코드 또는 명령 제안이 포함된다.

출력 예시 형태

3줄 요약
- 이 과정은 에이전트 개념, 프레임워크, 실전 과제로 이어진다.
- 입문자는 Unit 0에서 코스 구조를 먼저 잡고 Unit 1에서 에이전트 기본 개념을 익히는 편이 안정적이다.
- 바로 손을 움직이려면 smolagents 섹션에서 최소 예제를 실행해보는 것이 가장 빠르다.
 
추천 순서
1. unit0
2. unit1
3. smolagents
...

이 실습에서 확인할 공식 포인트

1) 코스 구조

공식 저장소와 코스 소개 페이지는 전체 구성을 0~4 유닛 + 보너스 유닛으로 정리한다. 특히 코스는 기초 이론, 핸즈온, 유스케이스, 최종 과제로 이어진다고 설명한다.

2) 권장 학습 속도

공식 소개 페이지는 각 챕터를 1주, 주당 3~4시간 정도로 잡도록 권장한다. 따라서 짧은 실습이라도 “오늘 볼 페이지”와 “다음 행동”을 함께 제안하는 흐름이 유용하다.

3) smolagents의 역할

smolagents 문서는 CodeAgent, 툴 연결, 다양한 모델 연결을 몇 줄 코드로 빠르게 시작할 수 있게 설계됐다고 설명한다. 이번 실습은 그 빠른 시작 감각을 그대로 옮겨온다.

트러블슈팅

1) ModuleNotFoundError: No module named 'smolagents'

원인:

• 가상환경 미활성화
• 설치가 중간 실패

해결:

source .venv/bin/activate
pip install "smolagents[toolkit]" requests beautifulsoup4

2) ImportError 또는 bs4 관련 오류

원인:

• beautifulsoup4가 빠졌거나 다른 파이썬에 설치됨

해결:

python -m pip install beautifulsoup4
python -c "from bs4 import BeautifulSoup; print('bs4 ok')"

3) 401, 403, 또는 모델 호출 인증 오류

원인:

• 환경에 따라 Hugging Face Inference 호출 시 인증이 필요할 수 있음

해결:

export HF_TOKEN=hf_your_token
python app.py

4) 페이지 요청 타임아웃 또는 ReadTimeout

원인:

• 네트워크 지연
• 공식 사이트 응답이 느림

해결:

• timeout=20 값을 40으로 늘린다.
• 먼저 브라우저에서 URL이 열리는지 확인한다.
• 사내망/방화벽 환경이면 모바일 핫스팟 등 다른 네트워크로 재시도한다.

5) 답변이 공식 정보보다 일반론으로 흐름

원인:

• 프롬프트에 “공식 정보만 사용” 제약이 약함
• 필요한 섹션 호출 수가 부족함

해결:

• 프롬프트에 공식 HF Agents Course 정보만 사용 문장을 유지한다.
• unit0, unit1, smolagents를 명시적으로 비교하도록 질문한다.

6) HTML 구조 변경으로 본문 추출이 빈약함

원인:

• 페이지 마크업이 바뀌어 p, li, h2 선택 결과가 줄어듦

해결:

• soup.select("main p, main li, article p, article li")처럼 선택자를 더 구체화한다.
• 최악의 경우 response.text 일부를 저장해 직접 어떤 태그 구조인지 확인한다.

실습 체크리스트

• 작업 폴더 생성 완료
• 가상환경 활성화 완료
• smolagents, requests, beautifulsoup4 설치 완료
• 기본 Q&A 실행 성공
• 질문 변경 후 재검증 성공
• 트러블슈팅 1개 이상 직접 복구

다음 확장 아이디어

• get_course_section()에 Unit 3, Unit 4를 추가해 진도 추천 에이전트로 확장하기
• 답변을 Markdown 파일로 저장하는 커스텀 툴을 붙이기
• DuckDuckGoSearchTool()을 추가해 공식 저장소 이슈/토론까지 비교하게 만들기
• 여러 섹션을 먼저 읽는 보조 에이전트를 붙여 멀티에이전트 실험으로 확장하기

마무리

이번 실습의 핵심은 “에이전트가 아무 말이나 하게 두는 것”이 아니라, 읽어도 되는 공식 정보원을 좁히고 그 위에서 행동하게 만드는 것이다. 이 습관을 잡아두면 이후 Unit 2 프레임워크 비교나 Unit 4 최종 과제 준비에서도 답변 품질이 훨씬 안정적이다.

---

생성형 AI 활용 고지

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