🤗 42. HF Agents Course 본편 1 - Hugging Face 에이전트 학습 지형과 첫 smolagents 실행

한 줄 목표: Hugging Face Agents Course가 어떤 순서로 에이전트를 가르치는지 잡고, smolagents로 가장 작은 에이전트를 직접 실행해 본다.

Hugging Face Agents Course는 크게 두 축으로 진행됩니다.

1. Unit 1에서 에이전트의 기본 개념을 이해한다.
2. Unit 2에서 smolagents, LangGraph, LlamaIndex 같은 프레임워크로 실제 구현을 배운다.

입문자라면 먼저 “에이전트는 결국 목표를 받고 → 생각하고 → 도구를 쓰고 → 결과를 보고 → 다시 판단하는 루프”라는 감각을 잡는 것이 중요합니다. 그리고 그 감각을 가장 짧게 확인하기 좋은 도구가 smolagents입니다.

코스 전체에서 본 오늘 위치

• GitHub 저장소 기준으로 코스는 Unit 0~4와 보너스 유닛으로 구성됩니다.
• 코스 소개 페이지 기준으로 Unit 1은 Agent Fundamentals, Unit 2는 Frameworks입니다.
• smolagents 공식 문서는 이 흐름 중 “가벼운 첫 구현”에 가장 잘 맞는 입문 프레임워크를 제공합니다.

flowchart TD
    A[HF Agents Course] --> B[Unit 1 Agent Fundamentals]
    A --> C[Unit 2 Frameworks]
    B --> B1[Thought / Action / Observation 이해]
    B --> B2[도구와 메시지 형식 이해]
    C --> C1[smolagents]
    C --> C2[LangGraph]
    C --> C3[LlamaIndex]
    C1 --> D[첫 에이전트 실행]

핵심은 이겁니다.

• Unit 1이 왜 에이전트가 필요한지를 설명한다면,
• smolagents는 그것을 가장 빠르게 손에 잡히게 만드는 도구입니다.

왜 smolagents부터 시작하면 좋은가

smolagents 공식 문서는 이 라이브러리를 “적은 코드로 에이전트를 만들고 실행하기 쉬운 오픈소스 Python 라이브러리”로 설명합니다. 초보자 기준 장점은 세 가지입니다.

• 코드 양이 적어서 구조가 눈에 보인다.
• CodeAgent로 계산, 조건 분기, 도구 사용 흐름을 이해하기 쉽다.
• 나중에 검색 도구, 사내 함수, API 호출로 확장하기 좋다.

즉, 처음부터 복잡한 오케스트레이션보다 에이전트의 최소 루프를 이해하는 데 적합합니다.

15분 실습: 첫 smolagents 에이전트 실행

아래 실습은 공식 smolagents Quickstart 흐름을 바탕으로, 한국어 학습용으로 재현 단계를 더 잘게 나눈 버전입니다.

준비물

• Python 3.10 이상
• 터미널
• 인터넷 연결
• Hugging Face 계정
• 필요 시 HF_TOKEN

Step 1) 작업 폴더 생성

도구

• 터미널

입력

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

성공 판정

pwd

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

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

도구

• Python venv
• pip

입력

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가 출력되면 성공.

Step 3) 첫 에이전트 코드 작성

파일

app.py

입력

from smolagents import CodeAgent, InferenceClientModel
 
model = InferenceClientModel()
agent = CodeAgent(tools=[], model=model)
 
result = agent.run("1부터 10까지의 합을 계산해줘.")
print(result)

설명

• InferenceClientModel()은 Hugging Face Inference 기반 모델 연결입니다.
• CodeAgent는 필요하면 코드를 써서 문제를 풉니다.
• 여기서는 도구 없이도 작은 계산을 수행하는 가장 단순한 형태를 먼저 확인합니다.

Step 4) 실행

실행 명령

python app.py

성공 판정

아래를 만족하면 됩니다.

• 프로그램이 에러 없이 종료된다.
• 출력에 55 또는 그에 해당하는 설명이 포함된다.
• “에이전트가 답을 생성했다”는 최소 실행 확인이 된다.

Step 5) 도구를 붙여 에이전트 느낌 강화

이제 같은 폴더에서 app.py를 아래처럼 바꿉니다.

입력

from smolagents import CodeAgent, InferenceClientModel, tool
 
@tool
def multiply(a: int, b: int) -> int:
    """Multiply two integers.
 
    Args:
        a: first integer
        b: second integer
    """
    return a * b
 
model = InferenceClientModel()
agent = CodeAgent(tools=[multiply], model=model)
 
result = agent.run("multiply 도구를 사용해서 27 곱하기 14를 계산하고 한 줄 설명을 덧붙여줘.")
print(result)

성공 판정

python app.py

• 출력에 378이 포함된다.
• 도구 사용 결과를 바탕으로 설명이 붙는다.
• 같은 계산을 다시 실행해도 결과가 안정적으로 재현된다.

이 실습에서 꼭 잡아야 할 개념

1) 에이전트는 LLM 단독 사용과 다르다

LLM만 쓰면 답변 생성은 가능하지만, 계산이나 외부 정보 접근은 흔들릴 수 있습니다. 에이전트는 여기에 도구 호출과 반복 판단 루프를 붙입니다.

2) 도구는 정확도와 재현성을 올리는 장치다

multiply는 단순하지만 실무에선 아래처럼 확장됩니다.

• 검색 도구
• 사내 API 호출 함수
• 문서 저장 함수
• 데이터베이스 조회 함수

3) 좋은 구조가 좋은 프롬프트를 이길 때가 많다

“정확히 계산해줘”라고 여러 번 말하는 것보다, 계산 함수를 도구로 제공하는 쪽이 훨씬 안정적입니다.

실무 적용 포인트

리서치 자동화

• 검색 도구 + 요약 도구를 연결해 초안 생성
• Observation 단계에서 출처 누락 여부 점검

운영 리포트 자동화

• 지표 조회 함수 + 계산 함수 + 메시지 전송 함수 결합
• 임계치 초과 시 후속 액션 분기

사내 지식 에이전트

• 문서 검색 도구를 붙여 최신 문서 확인 후 답변
• 틀릴 위험이 큰 영역일수록 도구 기반 설계를 우선

자주 막히는 문제

설치는 됐는데 import 오류가 날 때

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

가상환경이 활성화되지 않았을 가능성이 큽니다.

모델 호출 권한 오류가 날 때

export HF_TOKEN=hf_your_token
python app.py

실행 환경에 따라 인증이 필요할 수 있습니다.

도구를 잘 안 쓰는 것처럼 보일 때

프롬프트에 아래처럼 명시합니다.

• 도구를 사용해서
• 계산 근거를 함께 설명해줘
• 마지막에 결과 검증도 해줘

요약

HF Agents Course 초반부를 따라갈 때 가장 중요한 첫 감각은 “에이전트란 결국 답변 생성기가 아니라 목표 달성을 위해 도구를 쓰는 실행 루프”라는 점입니다. smolagents는 이 구조를 가장 짧은 코드로 확인하게 해 주므로, 본편 1편의 출발점으로 아주 좋습니다.

다음 편에서 이어가기 좋은 주제

• CodeAgent와 ToolCallingAgent 차이
• 계산기/검색기 도구를 함께 붙인 멀티스텝 에이전트
• 에이전트가 중간 결과를 보고 다음 행동을 바꾸는 방식

---

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 구조와 설명 문장을 정리했고, Hugging Face Agents Course GitHub 저장소·공식 학습 페이지·smolagents 공식 문서를 기준으로 사람이 단계, 명령, 성공 판정, 실무 적용 포인트를 검토해 편집했습니다.