🤗 45. HF Agents Course 본편 1 - Think-Act-Observe와 Alfred 첫 에이전트 흐름 이해하기

한 줄 목표: HF Agents Course Unit 1의 핵심 개념을 Think → Act → Observe 루프로 이해하고, smolagents로 첫 에이전트를 직접 실행해본다.

Hugging Face Agents Course의 Unit 1은 에이전트를 한 문장으로 정리하면 무엇인지부터 잡아줍니다. 핵심은 에이전트가 LLM을 머리처럼 쓰되, 필요할 때 도구를 호출하고, 결과를 보고 다음 행동을 결정하는 실행 루프라는 점입니다.

공식 코스 소개에서도 Unit 1의 초점은 아래 네 가지입니다.

• 에이전트가 무엇인지 이해하기
• LLM이 에이전트 안에서 어떤 역할을 하는지 이해하기
• 도구와 액션을 연결하는 방식 보기
• Think → Act → Observe 워크플로우를 따라 첫 에이전트 만들기

오늘 꼭 잡아야 할 그림

flowchart LR
    A[사용자 목표 입력] --> B[Think
무엇을 해야 하나?]
    B --> C[Act
도구 호출 또는 코드 실행]
    C --> D[Observe
결과 확인]
    D --> E{목표 달성?}
    E -- 아니오 --> B
    E -- 예 --> F[최종 답변 반환]

이 도식이 중요한 이유는 초보자가 에이전트를 그냥 “똑똑한 챗봇”으로 오해하기 쉽기 때문입니다. 실제로는 한 번 답하고 끝나는 모델 호출보다 판단-행동-검증 루프에 더 가깝습니다.

LLM만 있을 때와 에이전트일 때의 차이

일반 LLM 호출

• 질문을 받는다.
• 바로 답을 생성한다.
• 계산, 검색, 외부 시스템 반영이 필요해도 내부 추정에 기대기 쉽다.

에이전트

• 목표를 받는다.
• 지금 바로 답할지, 도구를 쓸지 판단한다.
• 도구 실행 결과를 본다.
• 부족하면 한 번 더 행동한다.
• 최종 답을 정리한다.

실무에서는 이 차이가 그대로 정확도, 재현성, 자동화 가능성 차이로 이어집니다.

왜 smolagents가 입문용으로 좋나

smolagents 문서는 이 라이브러리를 “적은 코드로 에이전트를 쉽게 만들고 실행하는 오픈소스 Python 라이브러리”로 설명합니다. 입문자에게 특히 좋은 이유는 아래와 같습니다.

• 최소 코드로 첫 실행이 가능하다.
• CodeAgent와 ToolCallingAgent의 차이를 비교하며 배우기 좋다.
• 도구를 Python 함수처럼 붙일 수 있어 실무 확장이 쉽다.

이번 글은 가장 이해가 쉬운 CodeAgent 기준으로 진행합니다.

20분 실습: Alfred 감각으로 첫 에이전트 실행하기

아래 실습은 초보자가 그대로 따라할 수 있도록 도구 / 입력 / 실행 명령 / 성공 판정 기준으로 정리했습니다.

준비물

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

Step 1) 실습 폴더와 가상환경 만들기

도구

• 터미널

입력

mkdir -p ~/hf-agents-course-unit1
cd ~/hf-agents-course-unit1
python3 -m venv .venv
source .venv/bin/activate

실행 명령

python --version
which python

성공 판정

• Python 버전이 3.10 이상이다.
• 경로가 .venv 아래 Python을 가리킨다.

Step 2) smolagents 설치하기

도구

• pip

입력

python -m pip install -U pip
pip install 'smolagents[toolkit]'

실행 명령

python -c "import smolagents; print(smolagents.__version__)"

성공 판정

• 버전 문자열이 출력된다.
• ModuleNotFoundError 없이 끝난다.

Step 3) 가장 작은 에이전트 만들기

도구

• 편집기

입력 파일

alfred_min.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는 필요하면 Python 코드 형태로 행동을 만든다.
• 지금은 도구 없이도 에이전트 실행 루프가 도는지부터 확인한다.

실행 명령

python alfred_min.py

성공 판정

• 실행이 정상 종료된다.
• 출력에 55 또는 동등한 설명이 포함된다.

Step 4) 첫 도구 붙이기

이제 에이전트가 행동할 수 있는 손을 하나 달아준다.

도구

• 편집기

입력 파일

alfred_tool.py

입력 내용

from smolagents import CodeAgent, InferenceClientModel, tool
 
@tool
def get_discounted_price(price: int, discount_percent: int) -> int:
    """Return discounted price.
 
    Args:
        price: original price
        discount_percent: percentage discount to apply
    """
    return price - (price * discount_percent // 100)
 
model = InferenceClientModel()
agent = CodeAgent(tools=[get_discounted_price], model=model)
 
result = agent.run(
    "정가 120000원 상품에 15% 할인을 적용한 최종 가격을 계산하고, 할인 금액도 짧게 설명해줘."
)
print(result)

실행 명령

python alfred_tool.py

성공 판정

• 출력에 최종 가격 102000이 포함된다.
• 할인 금액 18000에 대한 설명이 들어간다.
• 같은 입력으로 재실행해도 결과가 흔들리지 않는다.

Step 5) Think → Act → Observe를 눈으로 해석하기

위 실습에서 내부적으로 기대하는 흐름은 대략 이렇습니다.

1. Think: 할인 계산은 추정하지 말고 도구를 쓰는 게 낫다고 판단
2. Act: get_discounted_price(120000, 15) 호출
3. Observe: 결과 102000 확인
4. Think: 할인 금액 18000도 함께 설명해야 함을 판단
5. Final: 사용자용 문장으로 정리

여기서 중요한 건 정답 숫자만이 아닙니다. 에이전트가 언제 모델 추론을 쓰고, 언제 도구를 쓰는지 분리해서 설계할 수 있다는 점입니다.

실무 적용 포인트

1) 가격/정산/지표 계산 자동화

계산을 프롬프트에만 맡기지 말고 함수 도구로 빼면 결과 검증이 쉬워집니다.

2) 검색형 업무 자동화

검색 도구를 붙이면 에이전트가 최신 문서를 확인한 뒤 답하도록 만들 수 있습니다. 실무에서 출처가 중요한 경우 특히 유리합니다.

3) 사내 API 연동

오늘의 get_discounted_price() 자리에 아래가 들어갈 수 있습니다.

• 주문 조회 함수
• CRM 업데이트 함수
• 사내 문서 검색 함수
• 리포트 저장 함수

즉, Unit 1의 개념은 곧바로 운영 자동화 설계로 연결됩니다.

초보자가 자주 막히는 지점

인증 오류가 날 때

InferenceClientModel() 사용 시 환경에 따라 Hugging Face 토큰이 필요할 수 있습니다.

export HF_TOKEN=hf_your_token
python alfred_min.py

도구 설명이 부실할 때

@tool 함수의 docstring과 인자 설명이 짧거나 모호하면 에이전트가 도구를 덜 안정적으로 쓸 수 있습니다. 도구 이름, 목적, 인자 의미를 분명히 적는 것이 중요합니다.

왜 CodeAgent부터 배우나

공식 smolagents 가이드 기준으로 CodeAgent는 도구 조합, 반복, 변형 같은 표현력이 좋습니다. 대신 코드 실행 안전성은 더 신경 써야 합니다. 반대로 ToolCallingAgent는 구조화된 호출이라 더 안전하고 예측 가능하지만 복잡한 조합은 덜 유연합니다.

오늘 정리

HF Agents Course 본편 1편에서 가장 먼저 익혀야 할 것은 라이브러리 이름이 아닙니다. 에이전트는 목표를 받고, 생각하고, 행동하고, 결과를 확인하며 반복하는 구조라는 감각입니다.

그리고 smolagents는 그 구조를 아주 짧은 코드로 보여주기 때문에 첫 학습용으로 적합합니다. 오늘 실습이 재현됐다면, 다음 단계에서는 검색 도구나 외부 API를 붙여 **“말하는 모델”에서 “일하는 에이전트”**로 넘어갈 준비가 된 것입니다.

다음 편 추천 주제

• CodeAgent와 ToolCallingAgent 차이
• 검색 도구를 붙인 정보 탐색형 에이전트
• 안전한 코드 실행과 sandbox 개념

---

생성형 AI 활용 고지

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