🤗 44. HF Agents Course 본편 1 - 코스 구조 이해부터 첫 smolagents 검증까지

한 줄 목표: Hugging Face Agents Course의 학습 지형을 먼저 잡고, smolagents 최소 예제를 직접 실행해 에이전트의 기본 감각을 확인한다.

Hugging Face Agents Course는 크게 두 단계로 이해하면 편합니다.

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

초보자에게 중요한 건 처음부터 복잡한 멀티에이전트 구조를 외우는 게 아닙니다. 먼저 에이전트가 목표를 받고, 필요하면 도구를 쓰고, 결과를 보고 다시 판단하는 흐름을 손으로 재현해보는 게 핵심입니다. 그 출발점으로 가장 가벼운 선택지가 smolagents입니다.

코스 전체에서 오늘 위치 잡기

GitHub 저장소와 공식 학습 페이지 기준으로 코스는 다음 흐름으로 이어집니다.

flowchart TD
    A[HF Agents Course] --> B[Unit 0 온보딩]
    A --> C[Unit 1 Agent Fundamentals]
    A --> D[Unit 2 Frameworks]
    A --> E[Unit 3 Use Cases]
    A --> F[Unit 4 Final Assignment]
    C --> C1[Thought / Action / Observation]
    D --> D1[smolagents]
    D --> D2[LlamaIndex]
    D --> D3[LangGraph]
    D1 --> G[첫 실행 실습]

여기서 오늘 실습은 Unit 1의 개념을 Unit 2의 smolagents로 바로 확인하는 연결 지점에 해당합니다.

왜 smolagents부터 시작하면 좋은가

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

• 코드 양이 작아서 에이전트 구조가 눈에 잘 들어온다.
• CodeAgent 중심 예제가 많아 도구 사용 흐름을 이해하기 쉽다.
• 나중에 검색, 계산, 사내 함수, 외부 API 호출로 확장하기 좋다.

즉, 처음에는 “정말 에이전트가 일반 LLM 호출과 뭐가 다르지?”를 확인하는 데 가장 적합합니다.

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이 포함된다.
• 계산 결과에 짧은 설명이 함께 붙는다.
• 다시 실행해도 같은 결과를 재현할 수 있다.

Step 6) 작은 변형으로 루프 감각 확인

질문만 아래처럼 바꿔 다시 실행해보면 좋습니다.

입력

multiply 도구를 사용해서 19 곱하기 23을 계산하고, 마지막에 짝수인지 홀수인지도 말해줘.

실행 명령

python app.py

성공 판정

• 결과에 437이 포함된다.
• 마지막에 홀수라고 설명한다.
• 계산 후 판단까지 이어지는 흐름이 보인다.

이 실습에서 꼭 이해할 포인트

1) 에이전트는 LLM 단독 호출과 다르다

LLM만 쓰면 답은 만들 수 있지만 계산, 검색, 외부 도구 사용은 흔들릴 수 있습니다. 에이전트는 여기에 도구 호출과 반복 판단 루프를 붙입니다.

2) 도구는 정확도와 재현성을 높인다

오늘은 multiply 하나만 붙였지만, 실무에서는 아래처럼 바로 확장됩니다.

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

3) 좋은 구조가 좋은 프롬프트보다 더 중요할 때가 많다

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

실무 적용 포인트

리서치 자동화

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

운영 리포트 자동화

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

사내 지식 에이전트

• 문서 검색 도구를 붙여 최신 문서를 확인한 뒤 답변
• 틀리면 비용이 큰 영역일수록 도구 기반 설계를 우선

자주 막히는 문제

ModuleNotFoundError가 날 때

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

가상환경이 비활성 상태일 가능성이 큽니다.

모델 호출 권한 오류가 날 때

export HF_TOKEN=hf_your_token
python app.py

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

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

프롬프트에 아래처럼 명시하면 도움이 됩니다.

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

요약

HF Agents Course 본편 1편에서 먼저 가져가야 할 감각은 하나입니다. 에이전트는 답변 생성기가 아니라, 목표 달성을 위해 도구를 쓰는 실행 루프라는 점입니다. smolagents는 이 구조를 아주 짧은 코드로 보여주기 때문에 입문 실습으로 적합합니다.

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

• CodeAgent와 ToolCallingAgent 차이
• 검색 도구를 붙인 정보 탐색형 에이전트
• 계산기 + 검색기 조합으로 멀티스텝 태스크 풀기

---

생성형 AI 활용 고지

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