🤗 47. HF Agents Course 본편 1 - Unit 1 입문과 Alfred 첫 에이전트 전체 흐름

목표: Hugging Face Agents Course의 Unit 1이 무엇을 가르치는지 먼저 잡고, smolagents로 Alfred 스타일의 첫 에이전트를 직접 실행해 에이전트의 기본 작동 방식을 손으로 확인한다.

공식 코스 기준으로 HF Agents Course는 기초 개념 → 프레임워크 → 실전 유스케이스 → 최종 과제의 4개 큰 축으로 진행된다. 그중 Unit 1은 가장 중요하다. 여기서 에이전트가 무엇인지, LLM이 어떤 역할을 하는지, 도구를 어떻게 붙이는지, Think → Act → Observe 루프가 왜 필요한지를 이해해야 뒤의 smolagents·LangGraph·LlamaIndex 파트가 쉬워진다.

공식 Unit 1 소개는 마지막에 Alfred라는 첫 에이전트를 만들어 보게 한다. 즉, 이 단원은 이론만 읽는 파트가 아니라 개념을 바로 실행으로 연결하는 입문 실습 단원이다.

먼저 큰 그림부터

• GitHub 저장소: 코스 전체가 4개 유닛과 보너스 유닛으로 구성됨을 보여준다.
• 코스 소개 페이지: 기초 이론, 핸즈온, 과제, 챌린지 구조를 설명한다.
• Unit 1 소개: 에이전트, LLM, 도구, Think-Act-Observe, Alfred 첫 에이전트를 핵심 학습 목표로 둔다.
• smolagents 문서: 적은 코드로 CodeAgent를 만들고 도구를 붙일 수 있음을 보여준다.

Unit 1에서 실제로 배우는 것

1) 에이전트란 무엇인가

에이전트는 단순히 텍스트를 이어서 쓰는 챗봇이 아니다. 목표를 받고, 필요한 경우 생각하고, 도구를 호출하고, 결과를 관찰한 뒤 다음 행동을 결정하는 실행 주체에 가깝다.

2) LLM은 에이전트의 뇌 역할을 한다

공식 코스는 LLM을 에이전트의 “brain”으로 설명한다. 다만 LLM 혼자만으로는 외부 세계와 상호작용하기 어렵다. 그래서 계산, 검색, 파일 읽기 같은 작업은 도구(tool) 가 맡고, LLM은 어떤 도구를 언제 쓸지 결정한다.

3) Think → Act → Observe 루프가 핵심이다

에이전트는 보통 아래 흐름으로 움직인다.

flowchart LR
    U[사용자 목표] --> T[Think
문제 해석·계획]
    T --> A[Act
도구 호출·코드 실행]
    A --> O[Observe
결과 확인]
    O --> D{목표 달성?}
    D -- 아니오 --> T
    D -- 예 --> R[최종 답변]

이 루프를 이해하면 이후 프레임워크를 바꿔도 본질은 거의 같다.

4) 첫 에이전트 실습의 의미

Unit 1은 결국 “개념을 아는 것”보다 작은 성공 경험을 만드는 것에 가깝다. Alfred 같은 간단한 에이전트를 한 번 돌려보면,

• LLM이 어디까지 스스로 해결하는지
• 어떤 순간에 도구가 필요한지
• 출력이 왜 가끔 불안정한지
• 프롬프트와 도구 설계가 왜 중요한지

를 감으로 이해하게 된다.

이번 글에서 만들 것

아래 조건을 만족하는 입문용 Alfred 에이전트를 만든다.

• 입력: 간단한 질문 2개
• 도구: 계산기 1개
• 에이전트: smolagents.CodeAgent
• 성공 기준: 계산이 필요한 질문에서 도구를 활용해 안정적으로 정답을 낸다.

준비물

• Python 3.10+
• 터미널
• 인터넷 연결
• 선택: Hugging Face 토큰(HF_TOKEN)

실습: Alfred 스타일 첫 에이전트 만들기

Step 1) 작업 폴더 만들기

입력

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

성공 판정

pwd

• 경로 끝이 hf-agents-course-unit1-alfred면 통과.

Step 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-ok')"

• smolagents-ok가 출력되면 통과.

Step 3) 에이전트 코드 작성

alfred_first_agent.py 파일을 만들고 아래 코드를 넣는다.

from smolagents import CodeAgent, InferenceClientModel, tool
 
@tool
def calculator(expression: str) -> str:
    """Safely evaluate a simple arithmetic expression.
 
    Args:
        expression: Arithmetic 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 = [
    "7 * (13 + 5)는 얼마야? 계산 과정을 짧게 설명해줘.",
    "23.5와 19.8의 합을 구하고, 2로 나눈 값을 알려줘."
]
 
for i, question in enumerate(questions, start=1):
    print(f"\n=== Question {i} ===")
    print(f"INPUT: {question}")
    answer = agent.run(question)
    print("OUTPUT:")
    print(answer)

코드에서 꼭 볼 포인트

• @tool: 파이썬 함수를 에이전트가 쓸 수 있는 도구로 바꾼다.
• CodeAgent: 필요하면 코드 형태로 행동을 구성해 도구를 호출한다.
• InferenceClientModel(): Hugging Face 추론 모델을 기본값으로 연결한다.
• max_steps=5: 무한 루프를 막는 최소 안전장치다.

Step 4) 첫 실행

실행 명령

python alfred_first_agent.py

성공 판정

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

• 실행이 예외 없이 끝난다.
• === Question 1 ===과 === Question 2 ===가 출력된다.
• 두 질문 모두 숫자 결과가 포함된다.
• 적어도 계산이 필요한 질문에서 도구 사용 결과를 반영한 답이 나온다.

Step 5) 도구 없는 버전과 비교하기

이번에는 도구를 제거해 차이를 본다.

입력

tools=[calculator]를 tools=[]로 바꾼다.

실행 명령

python alfred_first_agent.py

성공 판정

• 같은 질문에 대해 답변 품질 차이를 관찰할 수 있다.
• 계산 설명이 더 모호해지거나, 숫자 신뢰도가 낮아질 수 있다.
• 이 차이를 확인하면 “왜 에이전트에 도구를 붙이는가”가 이해된다.

Step 6) 실무형 질문으로 바꿔보기

질문을 아래처럼 바꿔 다시 실행해본다.

입력

questions = [
    "광고 클릭률이 2.4%이고 노출이 12500회면 클릭 수는 몇 회야?",
    "월 구독료 19달러 상품을 37명이 쓰면 월 매출은 얼마야?"
]

실행 명령

python alfred_first_agent.py

성공 판정

• 클릭 수, 매출 같은 실무 숫자가 계산된다.
• 도구가 단순 데모가 아니라 업무 보조에 바로 연결됨을 확인할 수 있다.

초보자 기준으로 이해하면 좋은 핵심

에이전트는 “생각만 하는 모델”이 아니다

중요한 건 말 잘하는 것보다 문제를 풀기 위해 외부 기능을 사용할 수 있느냐다.

도구는 정답률을 끌어올리는 안전장치다

특히 계산, 검색, 파일 처리처럼 틀리면 바로 티 나는 작업은 도구 분리가 유리하다.

작은 도구 1개로도 학습 효과가 크다

처음부터 웹검색, 파일시스템, 데이터베이스를 다 붙일 필요 없다. 계산기 1개만 붙여도 에이전트 사고방식을 이해하기 충분하다.

실무 적용 포인트

1) 운영 지표 요약 봇

• CTR, CVR, ROAS, 매출 합계처럼 계산이 필요한 마케팅 리포트에 바로 응용 가능하다.

2) 고객 응대 전처리

• 상담 전에 주문 금액, 할인율, 남은 기간을 먼저 계산해 붙이는 보조 에이전트로 확장할 수 있다.

3) 내부 업무 자동화의 첫 발판

• 처음엔 계산기 도구 1개
• 다음엔 CSV 읽기 도구
• 그다음엔 API 호출 도구

이 순서로 키우면 실패 확률이 낮다.

자주 막히는 지점

1) ModuleNotFoundError: No module named 'smolagents'

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

2) 인증 또는 추론 호출 오류

공식 문서상 InferenceClientModel()은 Hugging Face 추론 환경을 쓰므로, 실행 환경에 따라 인증이 필요할 수 있다.

export HF_TOKEN=hf_your_token_here
python alfred_first_agent.py

3) 도구가 호출되지 않는 것처럼 보일 때

• 질문을 더 계산 중심으로 바꾼다.
• 숫자와 연산이 분명한 문제를 넣는다.
• max_steps를 너무 낮게 잡지 않는다.

4) 계산기 도구가 너무 위험해 보일 때

이번 코드는 입문용 예시다. 실제 운영에서는 eval 대신 파서 기반 계산기로 바꾸는 편이 더 안전하다. 다만 공식 smolagents 문서가 강조하듯, 핵심은 적은 코드로 에이전트 구조를 먼저 이해하는 것이다.

공식 자료와 연결해서 보면 좋은 순서

1. 코스 소개 페이지에서 전체 구조 확인
2. Unit 1 소개에서 학습 목표 확인
3. smolagents Quickstart로 최소 코드 패턴 익히기
4. 위 Alfred 예제를 직접 실행
5. 이후 Unit 2 프레임워크 비교로 넘어가기

한 줄 정리

HF Agents Course 본편 1의 핵심은 “에이전트란 무엇인가”를 추상적으로 이해하는 데서 끝나지 않는다. LLM + 도구 + Think-Act-Observe 루프를 작은 코드로 직접 돌려보며, 이후 모든 프레임워크 학습의 공통 뼈대를 몸에 익히는 것이 진짜 목표다.

---

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안과 예시 코드를 작성했고, Hugging Face Agents Course GitHub 저장소·공식 코스 소개·Unit 1 소개·smolagents 문서를 기준으로 사람이 재현 단계, 실행 명령, 성공 판정, 링크 반영 항목을 검토해 편집했습니다.