🤗 50. HF Agents Course 본편 1 - Unit 1 시작점과 smolagents 최소 실행 재현하기

목표: HF Agents Course 본편 1의 출발점을 이해하고, smolagents로 도구 없는 최소 에이전트와 도구 1개를 붙인 에이전트를 직접 재현한다.

Hugging Face Agents Course는 전체적으로 기초 개념 → 프레임워크 → 실전 유스케이스 → 최종 과제 순서로 구성되어 있다. 그중 Unit 1은 가장 중요한 입문 구간이다. 여기서 잡아야 하는 것은 복잡한 멀티에이전트가 아니라, 에이전트가 목표를 받고 생각하고 도구를 쓰고 결과를 확인하는 기본 루프다.

공식 코스와 smolagents 문서를 함께 보면 초보자가 먼저 잡아야 할 포인트는 네 가지다.

• 에이전트는 단순 답변기가 아니라 목표 해결 흐름을 가진다.
• LLM은 판단을 맡고, 도구는 계산·검색·조회 같은 실제 작업을 맡는다.
• 기본 루프는 Think → Act → Observe로 이해하면 된다.
• 첫 실습은 작고 확실하게 성공하는 편이 학습 효율이 높다.

이번 글에서 만들 큰 그림

flowchart LR
    A[사용자 목표 입력] --> B[LLM이 문제 해석]
    B --> C{도구 필요?}
    C -- 아니오 --> D[직접 응답 생성]
    C -- 예 --> E[도구 호출]
    E --> F[결과 관찰]
    F --> B
    D --> G[최종 답변]
    F --> G

이 도식만 이해해도 이후 Unit 2에서 smolagents, LangGraph, LlamaIndex를 볼 때 “문법”보다 “원리”가 먼저 보인다.

공식 자료 기준으로 본 Unit 1 핵심

1) 에이전트는 목표 지향적이다

일반 챗봇은 질문에 바로 답을 이어서 생성하는 데 강하다. 반면 에이전트는 문제를 해석하고, 필요한 수단을 고르고, 중간 결과를 확인하면서 답을 만든다.

2) 도구가 붙어야 실무성이 올라간다

공식 코스의 Unit 1 설명에는 도구, 생각, 행동, 관찰이 핵심 개념으로 들어간다. 이유는 단순하다. 계산, 검색, 파일 읽기, API 호출 같은 일은 모델이 추정만 하는 것보다 도구를 호출하는 편이 더 검증 가능하기 때문이다.

3) smolagents는 입문 실습에 잘 맞는다

smolagents 문서는 아주 적은 코드로 에이전트를 실행하는 Quickstart를 제공한다. 즉, 처음 배우는 사람에게는 “구조 이해 → 즉시 실행 → 작은 수정” 흐름이 좋다.

실습 목표

이번 실습은 2단계로 나눈다.

1. 도구 없는 최소 에이전트를 실행한다.
2. 계산기 도구 1개를 추가한 에이전트로 정확도가 왜 좋아지는지 확인한다.

준비물

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

실습 1) 작업 폴더 만들기

도구

• 터미널

입력

mkdir -p ~/hf-agents-course-unit1-minimal
cd ~/hf-agents-course-unit1-minimal

성공 판정

pwd

• 경로 끝이 hf-agents-course-unit1-minimal이면 성공.

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

• smolagents가 출력되면 성공.

실습 3) 도구 없는 최소 에이전트 만들기

파일명

minimal_agent.py

입력

from smolagents import CodeAgent, InferenceClientModel
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[],
    model=model,
    max_steps=4,
)
 
question = "1부터 10까지의 합을 계산하고 한 줄로 설명해줘."
result = agent.run(question)
print(result)

설명

• InferenceClientModel()은 Hugging Face 추론 모델을 연결하는 가장 간단한 진입점이다.
• CodeAgent는 필요할 때 코드 기반으로 행동 단계를 조직한다.
• tools=[]는 아직 외부 도구를 붙이지 않은 상태다.

실행 명령

python minimal_agent.py

성공 판정

아래 3개를 만족하면 된다.

1. 예외 없이 실행이 끝난다.
2. 합계 55가 포함된 응답이 나온다.
3. 짧은 설명 문장이 함께 출력된다.

실습 4) 계산기 도구 붙이기

이번에는 같은 구조에 계산기 도구를 넣는다.

파일명

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,
)
 
questions = [
    "17 * 24는 얼마야? 짧게 설명해줘.",
    "56.8과 19.2를 더한 뒤 2로 나눈 값을 알려줘."
]
 
for i, question in enumerate(questions, start=1):
    print(f"\n=== Question {i} ===")
    print(agent.run(question))

실행 명령

python tool_agent.py

성공 판정

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

1. Question 1, Question 2가 모두 출력된다.
2. 첫 번째 결과에 408이 포함된다.
3. 두 번째 결과에 38.0 또는 같은 의미의 값이 포함된다.
4. 프로그램이 예외 없이 종료된다.

실습 5) 도구 유무 차이 비교

같은 질문을 두 파일에 각각 넣고 결과를 비교해 본다.

비교 질문 예시

광고 노출 12800회, CTR 2.5%면 클릭 수는 몇 회야?

실행 명령

python minimal_agent.py
python tool_agent.py

성공 판정

• 도구 없는 버전은 맞을 수도 있지만, 계산을 추론에 의존한다.
• 도구 있는 버전은 계산 절차를 더 안정적으로 처리한다.
• 이 차이를 확인하면 “왜 에이전트에 도구를 붙이는가”가 명확해진다.

초보자 관점 핵심 정리

에이전트의 본질은 답변 생성보다 문제 해결 흐름이다

좋은 입문은 프롬프트 문구를 길게 꾸미는 게 아니라, 입력 → 판단 → 행동 → 관찰 → 응답 구조를 몸으로 익히는 것이다.

첫 도구는 계산기처럼 검증 쉬운 것이 좋다

결과가 바로 맞고 틀림으로 보이기 때문에, 에이전트 루프를 확인하기 좋다.

실습은 “작게 성공”이 중요하다

처음부터 웹 검색, 파일 처리, API 연동을 한꺼번에 붙이면 어디서 막혔는지 보기 어렵다. 최소 예제로 성공한 뒤 한 단계씩 확장하는 편이 안전하다.

실무 적용 포인트

1) 마케팅 숫자 검증

CTR, CPC, CVR, ROAS 계산 같은 반복 작업에 바로 응용할 수 있다.

2) 운영팀 정산 보조

수수료, 할인율, 환불액 계산처럼 숫자 정확도가 중요한 업무에 유용하다.

3) 다음 확장 경로

입문 이후에는 보통 아래 순서가 안정적이다.

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

자주 막히는 문제

ModuleNotFoundError

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

인증 또는 호출 오류

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

export HF_TOKEN=hf_your_token_here
python tool_agent.py

응답이 길거나 흔들릴 때

• 질문을 더 짧고 명확하게 쓴다.
• max_steps를 4~5 정도로 제한한다.
• 처음에는 계산처럼 정답이 분명한 과제로 테스트한다.

eval이 불안할 때

그 판단이 맞다. 운영 환경에서는 안전한 파서나 검증된 계산 모듈을 쓰는 편이 낫다. 여기서는 에이전트 구조 학습용 최소 예제로만 사용한다.

추천 학습 순서

1. 공식 코스 소개 페이지에서 전체 로드맵 확인
2. Unit 1의 에이전트 기본 개념 읽기
3. smolagents Quickstart 예제 실행
4. 이 글의 두 실습으로 도구 유무 차이 체감
5. 이후 실습편이나 Unit 2 프레임워크 비교로 확장

한 줄 요약

HF Agents Course 본편 1의 핵심은 화려한 데모가 아니라, 에이전트가 생각하고 행동하고 관찰하는 최소 루프를 직접 실행해 보는 것이다.

---

생성형 AI 활용 고지

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