🤗 51. HF Agents Course 본편 1 - 코스 지도부터 Alfred 첫 실행까지 한 번에 이해하기

목표: HF Agents Course의 전체 학습 지도를 먼저 잡고, Unit 1에서 강조하는 에이전트 기본 루프를 smolagents로 직접 재현한다.

Hugging Face Agents Course를 처음 보면 정보가 많아 보이지만, 실제 출발점은 단순하다. 먼저 이 코스가 어디까지 가는지를 이해하고, 그다음 에이전트가 어떻게 생각하고 행동하는지를 아주 작은 예제로 확인하면 된다. 공식 GitHub 저장소와 코스 페이지는 Unit 1을 에이전트 기초, Unit 2를 프레임워크, Unit 3를 유스케이스, Unit 4를 최종 과제로 배치한다. 즉, 첫 편에서 해야 할 일은 화려한 데모가 아니라 학습 지형 파악 + 최소 실행 성공이다.

먼저 잡아야 할 큰 그림

flowchart TD
    A[HF Agents Course 시작] --> B[Unit 1: 에이전트 기초]
    B --> C[문제 해석]
    C --> D[Think]
    D --> E[Act]
    E --> F[Observe]
    F --> G{목표 달성?}
    G -- 아니오 --> D
    G -- 예 --> H[최종 답변]
    A --> I[Unit 2: smolagents·LangGraph·LlamaIndex]
    A --> J[Unit 3: Agentic RAG 등 유스케이스]
    A --> K[Unit 4: 과제·평가]

이 그림의 핵심은 하나다. Unit 1은 이후 모든 프레임워크 학습의 공통 원리를 잡는 구간이라는 점이다.

공식 자료 기준 핵심 요약

1) 코스는 단계형이다

공식 저장소와 코스 소개 페이지 기준으로 HF Agents Course는 다음 순서로 진행된다.

• Unit 0: 온보딩
• Unit 1: 에이전트 기초
• Unit 2: 프레임워크 비교와 실습
• Unit 3: 실제 유스케이스
• Unit 4: 최종 과제와 평가

초보자라면 지금 당장 Unit 2 문법으로 뛰어들기보다, Unit 1의 도구·행동·관찰 개념을 먼저 몸에 익히는 편이 훨씬 빠르다.

2) 에이전트는 목표 해결 흐름이다

일반 챗봇은 답을 바로 생성하는 데 강하지만, 에이전트는 다음 흐름을 가진다.

• 목표를 해석한다.
• 필요한 도구를 고른다.
• 도구 실행 결과를 본다.
• 부족하면 한 번 더 시도한다.
• 충분하면 최종 답을 낸다.

이 구조를 보통 Think → Act → Observe로 이해하면 된다.

3) smolagents는 첫 실습용으로 가볍다

공식 smolagents 문서는 아주 적은 코드로 첫 에이전트를 만들 수 있게 설계되어 있다. 입문 단계에서는 이 단순함이 장점이다. 복잡한 오케스트레이션보다 작게 실행해 보고 바로 결과를 보는 경험이 중요하기 때문이다.

이번 글의 실습 목표

이번 글에서는 아래 2가지를 재현한다.

1. smolagents 실행 환경을 준비한다.
2. Alfred 스타일의 아주 작은 에이전트를 실행해 도구 사용 흐름을 확인한다.

준비물

• Python 3.10 이상
• 터미널
• 인터넷 연결
• 필요 시 Hugging Face 토큰 (HF_TOKEN)

실습 1) 작업 폴더 준비

도구

• 터미널

입력

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

성공 판정

pwd

• 출력 경로 끝이 hf-agents-course-alfred이면 성공.

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

입력

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

성공 판정

python -c "import smolagents; print(smolagents.__version__)"

• 버전 문자열이 출력되면 설치 성공.

실습 3) Alfred 스타일 첫 에이전트 작성

이번 예제는 “간단한 계산을 도구로 처리하고, 결과를 짧게 설명하는 보조 에이전트”다. 이름만 Alfred 스타일로 두고, 구조는 초보자에게 보이기 쉽게 최소화했다.

파일명

alfred_first_agent.py

입력

from smolagents import CodeAgent, InferenceClientModel, tool
 
@tool
def calculator(expression: str) -> str:
    """Evaluate a simple arithmetic expression.
 
    Args:
        expression: A math expression using numbers and + - * / ( )
    """
    allowed = set("0123456789+-*/(). ")
    if any(ch not in allowed for ch in expression):
        return "Only simple arithmetic is allowed."
 
    try:
        result = eval(expression, {"__builtins__": {}}, {})
        return str(result)
    except Exception as e:
        return f"calculation-error: {e}"
 
model = InferenceClientModel()
 
alfred = CodeAgent(
    tools=[calculator],
    model=model,
    max_steps=5,
)
 
question = "월 29달러 상품을 18명이 구독하면 월 매출은 얼마인지 계산하고 한 줄로 설명해줘."
result = alfred.run(question)
print(result)

실습 4) 실행하기

실행 명령

python alfred_first_agent.py

성공 판정

아래 3가지를 만족하면 된다.

1. 프로그램이 예외 없이 종료된다.
2. 결과에 522가 포함된다.
3. 계산 결과를 설명하는 짧은 한국어 또는 영어 문장이 함께 나온다.

실습 5) 도구 사용 여부 체감하기

이제 도구를 제거하고 다시 실행해 본다.

수정 포인트

tools=[]

즉, 아래 한 줄을

tools=[calculator]

이렇게 바꾼다.

tools=[]

실행 명령

python alfred_first_agent.py

성공 판정

• 응답은 생성될 수 있다.
• 하지만 계산 정확도와 재현성이 도구 버전보다 흔들릴 수 있다.
• 이 차이를 확인하면 Unit 1에서 왜 도구 개념을 강조하는지 감이 잡힌다.

초보자용 해설

왜 계산기부터 시작하나?

검색, 브라우저, API 도구는 매번 환경 변수가 많다. 반면 계산기는 입력과 정답이 명확해서 에이전트 루프를 배우기에 좋다.

왜 CodeAgent를 쓰나?

smolagents 문서에서 강조하듯 CodeAgent는 작업 단계를 코드처럼 표현할 수 있어, 도구 조합이나 반복 로직을 이해하기 쉽다. 입문 단계에서는 “에이전트가 중간 행동을 조직한다”는 감각을 잡기에 좋다.

왜 성공 판정을 따로 적나?

초보자는 “실행은 됐는데 내가 맞게 한 건지”에서 자주 막힌다. 그래서 실습 문서에는 반드시 도구 / 입력 / 실행 명령 / 성공 판정이 있어야 재현성이 올라간다.

실무 적용 포인트

1) 마케팅 숫자 검산

CTR, CPA, ROAS, 구독 매출 계산처럼 작은 숫자 업무를 먼저 맡기기 좋다.

2) 운영팀 반복 질문 자동화

반품률, 할인율, 정산액 같은 계산 질문을 에이전트 입력으로 바꿔 빠르게 처리할 수 있다.

3) 다음 확장 경로

추천 순서는 아래처럼 가면 안정적이다.

1. 계산기 도구
2. CSV 읽기 도구
3. 웹 검색 도구
4. 외부 API 도구
5. 멀티스텝 워크플로

자주 막히는 문제

ModuleNotFoundError: smolagents

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

모델 호출 또는 인증 오류

환경에 따라 Hugging Face 토큰이 필요할 수 있다.

export HF_TOKEN=hf_your_token_here
python alfred_first_agent.py

답이 장황하거나 불안정할 때

• 질문을 짧게 쓴다.
• max_steps를 4~5 정도로 제한한다.
• 처음엔 계산처럼 정답이 분명한 태스크로 검증한다.

eval이 부담될 때

그 우려는 맞다. 운영 환경에서는 안전한 파서나 검증된 수식 라이브러리로 바꾸는 편이 낫다. 여기서는 에이전트 구조 이해용 최소 예제로만 사용한다.

추천 학습 순서

1. 코스 소개 페이지로 전체 로드맵 확인
2. Unit 1의 기본 개념 읽기
3. smolagents Quickstart 확인
4. 이 글 실습으로 첫 에이전트 실행
5. 다음 글에서 도구 확장 또는 실습편으로 이동

한 줄 요약

HF Agents Course 본편 1에서 가장 중요한 첫 성공은 코스 전체 지도를 이해하고, 도구를 쓰는 최소 에이전트를 직접 한 번 돌려보는 것이다.

---

생성형 AI 활용 고지

이 문서는 생성형 AI로 초안을 작성한 뒤, Hugging Face Agents Course GitHub 저장소, 공식 코스 페이지, smolagents 문서를 기준으로 사람이 재현 단계, 명령어, 성공 판정, 링크 구조를 검토해 편집했습니다.