🤗 40. HF Agents Course 실습편 1 - 코스 문서 기반 학습 플래너 에이전트 만들기

목표: HF Agents Course 소개 페이지와 smolagents를 연결해, 코스 개요를 읽고 1주 학습 계획으로 정리하는 미니 프로젝트를 직접 재현한다.

이번 실습은 “검색/읽기 → 구조화 → 최종 답변” 흐름을 눈으로 확인하는 핸즈온입니다. Unit 0~2 초반을 막 보기 시작한 사람에게 특히 잘 맞습니다.

무엇을 만들까

사용자 입력:

• HF Agents Course를 1주 안에 입문하고 싶어. 하루 45분 기준으로 계획을 짜줘.

에이전트 출력:

• 코스 목적 요약
• 5일 학습 계획
• 각 일자별 추천 주제
• 마지막 점검 체크리스트

왜 이 실습이 좋은가

• 공식 코스 소개 페이지의 실제 정보를 바탕으로 답한다.
• CodeAgent가 필요 시 검색 도구를 써서 정보를 모은다.
• 최종 산출물이 단순 요약이 아니라 실행 가능한 학습 플랜이다.

전체 흐름

flowchart TD
    U[사용자 요청] --> A[CodeAgent]
    A --> S[DuckDuckGoSearchTool로 코스 정보 탐색]
    S --> O[검색 결과/공식 문서 확인]
    O --> P[학습일수·시간 기준으로 계획 구성]
    P --> R[최종 학습 플래너 출력]

준비물

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

Step 1) 작업 폴더 만들기

입력

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

성공 판정

• pwd 결과가 ~/hf-agents-course-lab01 이어야 한다.

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

입력

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

성공 판정

python -c "import smolagents; print('ok')"

• ok가 출력되면 통과.

Step 3) 실습 코드 작성

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

from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
)
 
prompt = """
Hugging Face Agents Course의 공식 공개 정보를 바탕으로,
입문자용 5일 학습 계획을 한국어로 작성해줘.
조건:
1) 하루 45분 기준
2) 먼저 코스 목적을 3줄 이내로 요약
3) Day 1~Day 5 형식으로 작성
4) 마지막에 체크리스트 4개 추가
5) 정보가 불충분하면 추정이라고 명시
"""
 
result = agent.run(prompt)
print(result)

코드 설명

• InferenceClientModel() : Hugging Face Inference 기반 기본 모델 사용
• DuckDuckGoSearchTool() : 코스 페이지/저장소 정보를 찾기 위한 검색 도구
• CodeAgent(...) : 필요한 경우 검색 후 답변을 재구성
• agent.run(prompt) : 실제 실행

Step 4) 실행

실행 명령

python app.py

성공 판정

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

• 실행이 에러 없이 끝난다.
• 출력에 코스 목적 요약이 포함된다.
• Day 1 ~ Day 5가 모두 나온다.
• 마지막에 체크리스트가 붙는다.

Step 5) 입력 바꿔서 한 번 더 검증

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

검증 입력

HF Agents Course를 빠르게 훑고 바로 smolagents 실습까지 가고 싶어.
3일 학습 계획으로 줄여서, 이론/실습 비중도 함께 적어줘.

성공 판정

• 3일 계획으로 재구성된다.
• 실습 중심이라는 요청이 답변에 반영된다.
• 단순 복붙이 아니라 일정과 우선순위가 바뀐다.

출력 예시 형태

코스 목적 요약
- 에이전트의 개념, 도구 사용, 프레임워크 활용을 배운다.
- smolagents, LangGraph, LlamaIndex 같은 라이브러리를 실습한다.
- 과제/챌린지 기반으로 에이전트를 평가하고 개선한다.
 
Day 1
- Unit 0 개요 읽기
- Unit 1 핵심 개념 정리
...

트러블슈팅

1) ModuleNotFoundError: smolagents

원인:

• 가상환경이 활성화되지 않았거나 설치가 중간에 실패함

해결:

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

2) 모델 호출 시 인증/권한 오류

원인:

• 환경에 따라 Hugging Face 토큰이 없으면 기본 호출이 막힐 수 있음

해결:

export HF_TOKEN=hf_your_token
python app.py

3) 검색 결과가 부정확하거나 너무 넓음

원인:

• 프롬프트가 추상적이라 코스 외부 자료까지 섞일 수 있음

해결:

• 프롬프트에 공식 공개 정보 기준, Hugging Face Agents Course, smolagents를 명시한다.
• 필요하면 Unit 0, Unit 1, smolagents 같은 키워드를 직접 넣는다.

4) 답변이 장황하고 계획처럼 보이지 않음

원인:

• 출력 형식 제약이 부족함

해결:

• Day 1~Day 5 형식, 체크리스트 4개, 3줄 요약 같은 형식 제약을 프롬프트에 넣는다.

5) 실행은 되지만 도구 호출이 거의 안 보임

원인:

• 모델이 내부 지식만으로 답하려고 할 수 있음

해결:

• 질문을 최신성/근거 중심으로 바꾼다.
• 예: 공식 코스 소개 페이지 기준으로 또는 현재 공개된 Unit 구성 기준으로를 추가한다.

실습 체크리스트

• 작업 폴더 생성 완료
• 가상환경 활성화 완료
• smolagents[toolkit] 설치 완료
• 기본 5일 학습 계획 실행 성공
• 3일 변형 입력 재실행 성공
• 트러블슈팅 최소 1개 직접 복구

여기서 배워야 할 핵심

이번 실습의 핵심은 정답 그 자체보다 에이전트가 외부 정보를 참고해 구조화된 결과를 만든다는 점입니다. 이 흐름을 이해하면 다음 단계에서 계산기, 커스텀 툴, 문서 검색형 에이전트로 확장하기 쉬워집니다.

다음 확장 아이디어

• DuckDuckGoSearchTool 대신 사내 위키 검색 도구 붙이기
• 결과를 Markdown 파일로 저장하는 커스텀 툴 추가
• 학습 계획 생성 뒤에 퀴즈 3개 생성 단계까지 이어 붙이기

---

생성형 AI 활용 고지

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