🤗 54. HF Agents Course 본편 1 - Tools·Thoughts·Actions·Observations를 Alfred 예제로 이해하기

목표: HF Agents Course Unit 1의 핵심 언어인 Tools, Thoughts, Actions, Observations를 이해하고, smolagents로 Alfred 스타일 첫 에이전트를 재현한다.

HF Agents Course 공식 소개는 학습 흐름을 기초 개념 → 프레임워크 → 유스케이스 → 최종 과제로 잡고 있다. 그래서 본편 1에서 가장 먼저 해야 할 일은 라이브러리 비교가 아니라, 에이전트가 어떤 단위로 생각하고 행동하는지 익히는 것이다.

공식 코스의 Unit 1 설명과 smolagents Quickstart를 같이 보면 초보자가 꼭 잡아야 할 축은 4개다.

• Thoughts: 지금 무엇을 해야 하는지 판단
• Actions: 실제로 실행할 행동 선택
• Tools: 계산, 조회, 검색 같은 바깥 기능 호출
• Observations: 행동 결과를 받아 다음 판단에 반영

Unit 1이 전체 코스에서 맡는 역할

flowchart TD
    A[Unit 0 온보딩] --> B[Unit 1 에이전트 기초]
    B --> C[Thoughts]
    B --> D[Actions]
    B --> E[Tools]
    B --> F[Observations]
    F --> G[첫 smolagents 재현]
    G --> H[Unit 2 프레임워크]
    H --> I[Unit 3 유스케이스]
    I --> J[Unit 4 최종 과제]

핵심은 단순하다. Unit 1을 이해하면 이후의 프레임워크 문법이 덜 낯설어진다.

왜 4요소가 중요한가

공식 코스는 에이전트를 단순 채팅 모델이 아니라 목표를 해결하는 루프로 설명한다. 이걸 초보자 기준으로 풀면 아래처럼 이해하면 된다.

1. 사용자가 목표를 준다.
2. 에이전트가 바로 답할지, 도구를 쓸지 생각한다.
3. 필요하면 도구를 실행한다.
4. 결과를 확인한다.
5. 부족하면 한 번 더 시도하고, 충분하면 답을 마무리한다.

즉 좋은 에이전트는 “말을 잘하는 모델”이 아니라 필요할 때 검증 가능한 행동을 끼워 넣는 시스템에 가깝다.

Alfred 예제로 보면 더 쉽다

이번 글에서는 에이전트를 “학습 비서 Alfred”라고 생각해 보자.

• 사용자의 질문: “이번 주 안에 HF Agents Course Unit 1을 끝내려면 오늘 무엇부터 해야 해?”
• Alfred의 생각(Thought): 오늘 가능한 시간을 먼저 계산해야겠네.
• Alfred의 행동(Action): 일정 계산 도구를 호출하자.
• Alfred의 도구(Tool): 남은 일수와 하루 가능 시간을 바탕으로 학습 블록 추천.
• Alfred의 관찰(Observation): 하루 40분씩 4번이면 되겠군.
• 최종 답변: 오늘은 온보딩 10분, Unit 1 핵심 개념 30분부터 시작하세요.

이 구조가 잡히면 이후 검색 도구, 파일 도구, API 도구도 같은 패턴으로 이해할 수 있다.

이번 글에서 재현할 것

이번 실습은 아래 3가지만 확실히 성공하면 된다.

1. Python 가상환경과 smolagents 설치
2. Alfred 스타일 일정 추천 도구 작성
3. 에이전트가 도구를 써서 학습 계획을 제안하는지 확인

준비물

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

실습 1) 작업 폴더 준비

도구

• 터미널

입력

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

실행 명령

pwd

성공 판정

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

실습 2) 가상환경과 smolagents 설치

도구

• 터미널

입력

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

실행 명령

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

성공 판정

• 버전 문자열이 출력되면 성공.

실습 3) Alfred 스타일 에이전트 작성

파일명

alfred_study_agent.py

입력

from smolagents import CodeAgent, InferenceClientModel, tool
 
@tool
def study_planner(days_left: int, minutes_per_day: int) -> str:
    """Create a simple study plan.
 
    Args:
        days_left: Number of days remaining.
        minutes_per_day: Available study minutes per day.
    """
    total_minutes = days_left * minutes_per_day
 
    if total_minutes < 60:
        return "시간이 부족합니다. 오늘 핵심 개념 요약만 먼저 보세요."
    if total_minutes < 180:
        return "오늘 Unit 1 개념 30분, 내일 첫 실습 30분, 마지막 날 복습 20분으로 진행하세요."
    return "오늘 개념 40분, 내일 첫 에이전트 실습 40분, 셋째 날 도구 확장 40분, 마지막 날 복습 20분을 추천합니다."
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[study_planner],
    model=model,
    max_steps=4,
)
 
question = "나는 이번 주 안에 HF Agents Course Unit 1을 끝내고 싶어. 4일 남았고 하루에 40분 가능해. 오늘부터 어떻게 공부하면 좋을지 알려줘."
result = agent.run(question)
print(result)

코드 이해 포인트

• @tool은 파이썬 함수를 에이전트가 호출 가능한 도구로 바꾼다.
• CodeAgent는 필요할 때 코드를 조합해 행동을 수행한다.
• max_steps=4는 입문 실습에서 과한 반복을 줄이는 안전장치다.
• 이 예제의 핵심은 답변 내용 자체보다 도구 호출 구조를 이해하는 것이다.

실습 4) 실행하기

도구

• 터미널

실행 명령

python alfred_study_agent.py

성공 판정

아래 3가지를 만족하면 성공이다.

1. 프로그램이 예외 없이 종료된다.
2. 결과에 오늘 또는 내일 같은 일정 제안이 포함된다.
3. 4일 × 40분 상황에 맞는 학습 계획이 자연스럽게 출력된다.

실습 5) Observation 감각 익히기

같은 파일에서 입력 질문만 아래처럼 바꿔 본다.

입력

question = "나는 주말까지 Unit 1만 빠르게 훑고 싶어. 2일 남았고 하루에 20분 가능해. 무엇부터 해야 할까?"

실행 명령

python alfred_study_agent.py

성공 판정

• 더 짧은 학습 계획이 나오면 성공.
• 즉 에이전트가 질문 조건 → 도구 호출 → 결과 반영 흐름을 수행한 것이다.

초보자용 쉬운 해설

Thoughts는 머릿속 메모다

에이전트는 질문을 받고 “이건 계산이 필요한가?”를 먼저 판단한다. 이게 Thoughts다.

Actions는 실제 버튼 누르기다

생각만 하고 끝나지 않고, 도구를 호출하거나 답변을 작성하는 실제 단계가 Actions다.

Tools는 정확도를 올리는 보조 장치다

모델이 감으로 답하는 대신 계산 함수나 검색 함수 같은 바깥 기능을 쓰면 결과가 더 재현 가능해진다.

Observations는 중간 결과 확인이다

도구를 쓴 뒤 결과를 읽고 다음 행동을 바꾸는 단계다. 이 감각이 있어야 에이전트가 루프를 돈다.

실무 적용 포인트

1) 교육 콘텐츠 학습 코치

문서량, 마감일, 하루 가능 시간을 받아 개인별 학습 계획을 추천할 수 있다.

2) 운영 체크리스트 자동화

남은 시간과 우선순위를 입력받아 “오늘 해야 할 일 3개”를 자동 제안하는 내부 도우미로 확장할 수 있다.

3) 다음 확장 순서

초보자라면 아래 순서가 안전하다.

1. 계산/분기 도구
2. 파일 읽기 도구
3. 웹 검색 도구
4. 외부 API 도구
5. 멀티에이전트 구조

자주 막히는 문제

ModuleNotFoundError: smolagents

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

인증 또는 호출 오류

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

export HF_TOKEN=hf_your_token_here
python alfred_study_agent.py

응답이 불안정할 때

• 질문을 더 짧고 명확하게 쓴다.
• max_steps를 4~5로 제한한다.
• 처음에는 검색보다 계산·분기처럼 정답 범위가 좁은 도구부터 검증한다.

오늘 기억할 한 줄

HF Agents Course 본편 1의 핵심은 에이전트가 답을 “즉흥적으로 생성”하는 존재가 아니라, 생각하고 도구를 쓰고 결과를 확인하는 루프라는 점을 이해하는 것이다.

---

생성형 AI 활용 고지

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