🤗 53. HF Agents Course 본편 1 - Unit 1 핵심 개념과 첫 도구형 에이전트 재현하기

목표: HF Agents Course의 출발점을 짚고, smolagents로 도구 1개가 붙은 첫 에이전트를 직접 실행해 본다.

Hugging Face Agents Course 공식 소개는 학습 흐름을 기초 개념 → 프레임워크 → 유스케이스 → 최종 과제로 잡고 있다. 그래서 본편 1에서 가장 중요한 일은 복잡한 멀티에이전트를 욕심내는 것이 아니라, 에이전트가 목표를 받고 생각하고 도구를 쓰고 결과를 확인하는 기본 루프를 몸으로 익히는 것이다.

특히 공식 코스와 smolagents 문서를 함께 보면 초보자가 처음 이해해야 할 포인트는 명확하다.

• 에이전트는 단순 채팅이 아니라 목표 해결 흐름이다.
• 도구는 계산·조회·검색 같은 검증 가능한 행동을 맡는다.
• 핵심 루프는 Think → Act → Observe로 이해하면 된다.
• 첫 실습은 작고 재현 가능해야 한다.

코스 전체에서 Unit 1이 맡는 역할

flowchart TD
    A[HF Agents Course 시작] --> B[Unit 0 온보딩]
    B --> C[Unit 1 에이전트 기초]
    C --> D[생각 Thought]
    C --> E[행동 Action]
    C --> F[관찰 Observation]
    C --> G[도구 Tool]
    C --> H[smolagents 첫 실행]
    H --> I[Unit 2 프레임워크 학습]
    I --> J[Unit 3 유스케이스]
    J --> K[Unit 4 과제·평가]

이 그림에서 핵심은 간단하다. Unit 1을 제대로 이해해야 이후 프레임워크 문법이 왜 그런지 보인다.

공식 자료 기준 핵심 요약

1) HF Agents Course는 단계형 학습 구조다

공식 GitHub 저장소와 코스 페이지 기준 주요 구성은 아래와 같다.

• Unit 0: 온보딩
• Unit 1: Agent Fundamentals
• Unit 2: Frameworks (smolagents, LlamaIndex, LangGraph)
• Unit 3: Use Cases
• Unit 4: Final Assignment
• Bonus Units: 함수호출 파인튜닝, 관측성/평가, 게임 에이전트 등

즉 지금 단계에서는 “어떤 라이브러리가 최고인가?”보다 에이전트의 공통 원리를 먼저 잡는 편이 맞다.

2) 에이전트는 답변기가 아니라 작업 흐름이다

Unit 1 설명의 핵심 키워드는 Tools, Thoughts, Actions, Observations다. 이 말은 곧 아래 순서를 뜻한다.

1. 목표를 이해한다.
2. 바로 답할지, 도구가 필요한지 판단한다.
3. 도구를 실행한다.
4. 결과를 보고 부족하면 다시 시도한다.
5. 최종 답변을 만든다.

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

공식 smolagents 문서는 몇 줄 코드로 CodeAgent를 실행하는 Quickstart를 제공한다. 초보자에게는 이 가벼움이 중요하다. 복잡한 설정보다 첫 성공 경험이 먼저 필요하기 때문이다.

이번 글에서 재현할 것

이번 글의 실습 목표는 딱 3가지다.

1. Python 가상환경과 smolagents를 설치한다.
2. 계산 도구 1개를 붙인 첫 에이전트를 만든다.
3. 실행 결과로 도구 기반 응답이 왜 안정적인지 확인한다.

준비물

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

실습 1) 작업 폴더 만들기

도구

• 터미널

입력

mkdir -p ~/hf-agents-course-unit1-first-agent
cd ~/hf-agents-course-unit1-first-agent

실행 명령

pwd

성공 판정

• 출력 경로 끝이 hf-agents-course-unit1-first-agent이면 성공.

실습 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__)"

성공 판정

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

실습 3) 첫 도구형 에이전트 파일 작성

이번 예제는 “간단한 매출 계산을 정확히 처리하고 한 줄 설명까지 붙이는 에이전트”다. 계산기처럼 결과가 분명한 문제부터 시작해야 초보자도 성공 여부를 쉽게 판단할 수 있다.

파일명

first_tool_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()
agent = CodeAgent(
    tools=[calculator],
    model=model,
    max_steps=5,
)
 
question = "월 39달러 상품을 24명이 구독하면 월 매출이 얼마인지 계산하고 짧게 설명해줘."
result = agent.run(question)
print(result)

코드 이해 포인트

• @tool은 일반 파이썬 함수를 에이전트 도구로 등록한다.
• InferenceClientModel()은 Hugging Face 추론 모델을 간단히 연결하는 기본 진입점이다.
• CodeAgent는 필요할 때 코드 기반으로 행동 단계를 구성한다.
• max_steps=5는 초보자 실습에서 과도한 반복을 줄이는 안전장치다.

실습 4) 에이전트 실행

도구

• 터미널

실행 명령

python first_tool_agent.py

성공 판정

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

1. 프로그램이 예외 없이 종료된다.
2. 결과에 936이 포함된다.
3. 계산 결과를 설명하는 짧은 문장이 함께 출력된다.

실습 5) 도구가 왜 중요한지 비교하기

이번에는 같은 파일에서 도구를 잠깐 제거해 본다.

수정 포인트

기존:

tools=[calculator]

변경:

tools=[]

실행 명령

python first_tool_agent.py

성공 판정

• 실행 자체는 될 수 있다.
• 하지만 계산 결과의 안정성과 재현성이 도구 사용 버전보다 흔들릴 수 있다.
• 이 차이를 확인하면 Unit 1에서 왜 도구를 강조하는지 바로 이해된다.

초보자용 쉬운 해설

왜 계산기 도구부터 시작하나?

검색이나 외부 API는 변수가 많다. 반면 계산 문제는 입력과 정답이 명확하다. 그래서 에이전트가 실제로 도구를 활용했는지 확인하기 좋다.

왜 CodeAgent를 먼저 보나?

smolagents 문서가 강조하듯 CodeAgent는 행동을 코드처럼 조합할 수 있다. 입문자 입장에서는 “생각만 하는 모델”이 아니라 “행동을 조직하는 에이전트”라는 차이를 이해하기 쉽다.

왜 성공 판정을 따로 적나?

실습 문서는 실행 명령만 있으면 부족하다. 성공 판정이 있어야 초보자도 막히지 않는다. 그래서 이 글은 각 단계마다 도구, 입력, 실행 명령, 성공 판정을 분리했다.

실무 적용 포인트

1) 마케팅 숫자 검산

CTR, CPC, 구독 매출, 할인율 계산처럼 정답이 분명한 반복 작업에 바로 붙일 수 있다.

2) 운영팀 FAQ 자동화

“이 가격에 3개월 매출이 얼마야?” 같은 질문은 작은 도구형 에이전트로 빠르게 처리할 수 있다.

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 first_tool_agent.py

응답이 너무 길거나 불안정할 때

• 질문을 더 짧게 쓴다.
• max_steps를 4~5 정도로 제한한다.
• 처음에는 계산처럼 정답이 뚜렷한 태스크로 검증한다.

eval이 불안할 때

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

추천 학습 순서

1. 공식 코스 소개 페이지에서 전체 로드맵 확인
2. Unit 1의 Tools / Thoughts / Actions / Observations 개념 읽기
3. smolagents Quickstart 확인
4. 이 글 실습으로 첫 도구형 에이전트 실행
5. 다음 글에서 실습편 또는 Unit 2 프레임워크 학습으로 확장

한 줄 요약

HF Agents Course 본편 1의 첫 성공은 에이전트의 기본 루프를 이해하고, 작은 도구 하나를 붙여 실제로 실행해 보는 것이다.

---

생성형 AI 활용 고지

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