🤗 48. HF Agents Course 본편 1 - 에이전트 기본 구조와 첫 smolagents 실행 가이드

목표: Hugging Face Agents Course의 Unit 1 관점에서 에이전트의 최소 구조를 이해하고, smolagents로 첫 실행까지 직접 재현한다.

Hugging Face Agents Course는 전체적으로 기초 개념 → 프레임워크 → 실전 유스케이스 → 최종 과제 흐름으로 설계되어 있다. 그중 본편 1은 가장 먼저 에이전트가 무엇인지, LLM은 어떤 역할을 하는지, 왜 도구가 필요한지를 잡아 주는 입문 구간이다.

공식 코스와 smolagents 문서를 같이 보면 초반에 꼭 이해해야 할 축은 네 가지다.

• 에이전트는 목표를 받고 여러 단계를 거쳐 답을 완성한다.
• LLM은 판단을 담당하지만 외부 작업은 도구가 맡는다.
• 핵심 루프는 Think → Act → Observe다.
• 입문 실습은 작은 도구 하나로도 충분히 학습 효과가 크다.

이 글에서 잡을 큰 그림

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

이 구조를 이해하면 뒤에서 LangGraph, LlamaIndex, smolagents를 보더라도 “프레임워크 문법”보다 “에이전트 본질”이 먼저 보인다.

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

1) 에이전트는 챗봇보다 넓은 개념이다

일반 챗봇은 질문에 바로 텍스트를 이어서 답하는 데 강하다. 반면 에이전트는 목표를 보고, 필요한 수단을 고르고, 중간 결과를 확인하며, 다음 행동을 결정한다.

2) LLM은 뇌, 도구는 손발에 가깝다

공식 코스는 LLM을 에이전트의 중심 판단기로 본다. 하지만 계산, 검색, 파일 읽기, API 호출 같은 일은 모델이 머릿속으로만 처리하기보다 검증 가능한 도구를 쓰는 편이 안정적이다.

3) Think-Act-Observe가 실전 감각의 시작점이다

이 루프를 이해하면 왜 어떤 질문은 잘 풀고 어떤 질문은 틀리는지 설명이 쉬워진다.

• Think: 지금 무엇을 해야 하는지 해석
• Act: 필요한 도구 호출 또는 코드 실행
• Observe: 나온 결과 확인
• Repeat: 아직 부족하면 다음 단계 반복

4) 첫 실습은 “작게 성공하기”가 중요하다

처음부터 복잡한 웹 에이전트를 만들 필요는 없다. smolagents 문서도 아주 적은 코드로 시작하는 방식을 권장한다. 입문 단계에서는 계산기 같은 단순 도구 하나만 붙여도 충분하다.

실습 목표

이번 실습에서는 아래 조건의 아주 작은 에이전트를 만든다.

• 프레임워크: smolagents
• 모델 연결: InferenceClientModel
• 도구: 계산기 1개
• 실행 목표: 숫자 계산이 들어간 질문 2개를 안정적으로 처리

준비물

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

실습 1) 작업 폴더 준비

도구

• 터미널

입력

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

성공 판정

pwd

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

실습 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) 첫 에이전트 코드 작성

파일명

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

코드 해설

• @tool: 일반 파이썬 함수를 에이전트용 도구로 바꾼다.
• CodeAgent: 필요하면 코드 형태로 작업 단계를 구성한다.
• InferenceClientModel(): Hugging Face 추론 모델 연결용 기본 진입점이다.
• max_steps=5: 초보자 실습에서 루프 폭주를 줄이는 안전장치다.

실습 4) 첫 실행

실행 명령

python first_agent.py

성공 판정

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

1. 프로그램이 예외 없이 종료된다.
2. === Question 1 ===, === Question 2 ===가 모두 출력된다.
3. 각 질문에 숫자 결과가 포함된다.
4. 계산 문제에서 계산기 도구의 결과를 반영한 답변이 나온다.

실습 5) 도구 유무 비교

도구의 필요성을 더 선명하게 보려면 한 번 비교해 보는 게 좋다.

입력

아래 한 줄만 바꾼다.

tools=[]

즉, 원래의

tools=[calculator]

를 비운다.

실행 명령

python first_agent.py

성공 판정

• 답변은 나오더라도 계산 신뢰도가 흔들릴 수 있다.
• 설명은 그럴듯한데 숫자가 틀릴 가능성이 생긴다.
• 이 차이를 확인하면 “왜 도구를 붙이는가”가 바로 이해된다.

실습 6) 실무형 입력으로 바꿔보기

이제 조금 더 업무에 가까운 질문으로 바꿔 본다.

입력

questions = [
    "광고 노출 12800회, CTR 2.5%면 클릭 수는 몇 회야?",
    "월 구독료 29달러 상품을 43명이 쓰면 월 매출은 얼마야?"
]

실행 명령

python first_agent.py

성공 판정

• 클릭 수, 매출 같은 실무 숫자가 바로 계산된다.
• 단순 데모를 넘어 운영 숫자 보조 에이전트로 확장 가능하다는 감이 온다.

초보자 포인트만 골라서 정리

에이전트의 핵심은 “외부 기능 사용”이다

말을 잘 만드는 것만으로는 부족하다. 실제 업무에서는 정확한 계산, 검색, 조회, 실행이 중요하다.

작은 도구 1개가 학습 효율이 높다

처음부터 도구 5개를 붙이면 오히려 헷갈린다. 계산기처럼 결과가 명확한 도구부터 시작하면 에이전트 루프가 잘 보인다.

프롬프트보다 구조가 먼저다

입문 단계에서는 멋진 프롬프트보다 입력 → 판단 → 도구 → 관찰 → 응답 구조를 몸에 익히는 게 더 중요하다.

실무 적용 포인트

1) 마케팅 리포트 보조

CTR, CPC, CVR, 매출 합계 계산처럼 숫자 오류가 바로 드러나는 작업에 적합하다.

2) 운영팀 계산 자동화

환불액, 할인율, 수수료, 정산 금액 계산에 연결하기 쉽다.

3) 다음 단계 확장 경로

가장 안정적인 확장 순서는 보통 이렇다.

1. 계산기 도구
2. CSV 읽기 도구
3. 외부 API 호출 도구
4. 검색/브라우저 도구

자주 막히는 문제

ModuleNotFoundError

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

인증 또는 모델 호출 오류

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

export HF_TOKEN=hf_your_token_here
python first_agent.py

도구 호출이 잘 안 보일 때

• 계산이 분명한 질문으로 바꾼다.
• 한 번에 너무 복잡한 요구를 넣지 않는다.
• max_steps를 지나치게 낮게 두지 않는다.

eval이 불안할 때

맞다. 운영 환경에서는 더 안전한 파서 기반 계산 방식이 좋다. 다만 이번 예제의 목적은 에이전트 구조 이해이므로 최소 예시로 보는 편이 맞다.

추천 학습 순서

1. 공식 코스 소개 페이지로 전체 구조 확인
2. Unit 1에서 에이전트 기본 개념 읽기
3. smolagents Quickstart 구조 확인
4. 이 글의 예제로 첫 실행 재현
5. 이후 실습편이나 Unit 2 프레임워크 비교로 이동

한 줄 요약

HF Agents Course 본편 1의 출발점은 복잡한 멀티에이전트가 아니다. LLM이 도구를 써서 문제를 푸는 최소 구조를 직접 돌려보는 것이 가장 중요하다.

---

생성형 AI 활용 고지

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