🤗 41. HF Agents Course 본편 1 - 에이전트는 어떻게 생각하고 도구를 쓰는가

한 줄 목표: Hugging Face Agents Course가 말하는 에이전트의 기본 구조를 이해하고, smolagents로 가장 작은 재현 실습까지 끝낸다.

Hugging Face Agents Course의 Unit 1은 에이전트를 단순한 “대답 잘하는 모델”이 아니라, 목표를 받고 생각하고 행동하고 관찰을 반영하는 실행 주체로 설명합니다. 이어지는 Unit 2에서는 이 구조를 smolagents, LangGraph, LlamaIndex 같은 프레임워크로 구현합니다.

초보자 기준으로는 이 한 가지를 먼저 잡으면 됩니다.

• LLM은 답을 생성한다.
• 에이전트는 답 생성 + 도구 사용 + 중간 판단까지 묶는다.
• 그래서 검색, 계산, 파일 처리처럼 모델 단독으로 불안정한 작업을 더 안정적으로 처리할 수 있다.

HF Agents Course에서 보는 에이전트의 최소 구조

flowchart LR
    G[사용자 목표] --> T[Thought
무엇을 해야 하지?]
    T --> A[Action
도구 호출 또는 코드 실행]
    A --> O[Observation
결과 확인]
    O --> D{목표 달성?}
    D -- 아니오 --> T
    D -- 예 --> R[최종 응답]

이 루프가 중요한 이유는 간단합니다.

1. Thought: 지금 무엇이 부족한지 판단
2. Action: 검색, 계산, 함수 호출 같은 실제 행동 수행
3. Observation: 행동 결과를 다시 입력으로 사용
4. 반복: 목표를 달성할 때까지 조정

실무에서는 이 구조 덕분에 아래 같은 일이 가능해집니다.

• FAQ 봇이 모르면 문서를 찾고 답하기
• 운영 봇이 숫자를 직접 계산하고 보고하기
• 리서치 봇이 검색 결과를 모아 요약하기

왜 smolagents가 입문용으로 좋은가

Hugging Face 문서 기준으로 smolagents는 적은 코드로 에이전트 핵심 구조를 바로 볼 수 있는 경량 라이브러리입니다. 특히 CodeAgent는 행동을 코드 형태로 표현하므로 다음 장점이 있습니다.

• 계산/조건문/반복문을 자연스럽게 사용 가능
• 도구 호출 과정을 코드처럼 읽을 수 있음
• “검색 → 계산 → 정리” 같은 멀티스텝 작업을 짧은 예제로 재현하기 쉬움

오늘 바로 해보는 10분 실습

아래 실습은 “에이전트가 계산기를 도구처럼 써서 더 안정적으로 답한다”는 감각을 익히기 위한 최소 예제입니다.

준비물

• Python 3.10+
• 터미널
• 인터넷 연결
• 가상환경(venv)
• 필요 시 Hugging Face 토큰 (HF_TOKEN)

Step 1) 작업 폴더 만들기

입력

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

성공 판정

pwd

• 결과 경로 끝이 hf-agents-course-ep1이면 성공.

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

입력

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install smolagents

성공 판정

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

• smolagents가 출력되면 통과.

Step 3) 실습 코드 작성

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("27 곱하기 14를 계산하고, 결과가 왜 맞는지 한 줄로 설명해줘.")
print(result)

코드 설명

• @tool: 일반 Python 함수를 에이전트 도구로 등록
• multiply: 모델이 직접 암산하지 않고 호출할 수 있는 계산 도구
• InferenceClientModel(): Hugging Face Inference 기반 모델 연결
• CodeAgent(...): 필요하면 코드를 작성해 도구를 사용하고 답을 구성

Step 4) 실행

실행 명령

python app.py

성공 판정

아래 3개를 모두 만족하면 성공입니다.

• 실행이 에러 없이 끝난다.
• 출력에 378이 포함된다.
• 답변에 계산 근거나 짧은 설명이 함께 나온다.

Step 5) 프롬프트를 바꿔 루프 확인

이번엔 app.py의 마지막 줄 질문을 아래처럼 바꿔 다시 실행합니다.

입력

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

성공 판정

• 결과에 437이 포함된다.
• 마지막에 홀수라고 설명한다.
• 단순 숫자 출력이 아니라, 계산 후 판단까지 붙는다.

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

1) 에이전트는 모델 + 도구 + 루프다

모델 하나만 있으면 말은 잘할 수 있어도 계산, 검색, 외부 시스템 접근은 흔들릴 수 있습니다. 에이전트는 여기에 도구와 반복 판단을 붙여 실행 가능한 시스템으로 바꿉니다.

2) 도구는 “능력 확장 슬롯”이다

오늘은 multiply 하나만 붙였지만, 실제로는 아래로 확장됩니다.

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

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

계산 문제를 모델에게 “조심해서 계산해”라고 말하는 것보다, 계산 도구를 붙이는 편이 재현성과 안정성이 높습니다.

실무 적용 포인트

콘텐츠/리서치 작업

• 검색 도구 + 요약 도구를 묶어 조사 초안 생성
• 출처 누락 여부를 Observation 단계에서 점검

운영 자동화

• 지표 조회 도구 + 계산 도구 + 슬랙/텔레그램 전송 도구 조합
• 임계치 초과 시 다음 액션 분기 가능

사내 지식봇

• 벡터 검색 또는 문서 조회 도구 연결
• 답변 전 최신 문서를 다시 확인하도록 루프 설계

자주 막히는 지점

ImportError 또는 ModuleNotFoundError

원인:

• 가상환경 미활성화 또는 설치 실패

해결:

source .venv/bin/activate
pip install smolagents

모델 호출 권한 오류

원인:

• 실행 환경에 따라 인증이 필요할 수 있음

해결:

export HF_TOKEN=hf_your_token
python app.py

도구를 잘 안 쓰는 것처럼 보임

원인:

• 질문이 너무 단순하면 모델이 직접 답하려 할 수 있음

해결:

• 프롬프트에 도구를 사용해서를 명시
• 계산 근거, 단계, 판정 조건을 함께 요구

요약

HF Agents Course의 초반부에서 가장 먼저 익혀야 할 것은 화려한 프레임워크가 아닙니다. 에이전트가 목표를 받고, 필요한 도구를 쓰고, 결과를 보고, 다시 판단하는 루프입니다. 이 감각만 잡히면 다음 단계의 검색형 에이전트, 코드 실행형 에이전트, 멀티에이전트 구조도 훨씬 쉽게 이해됩니다.

다음에 이어 보면 좋은 주제

• CodeAgent와 ToolCallingAgent 차이
• 검색 도구를 붙인 정보 탐색형 에이전트
• 계산기/파일 저장 도구를 묶은 자동화형 에이전트

---

생성형 AI 활용 고지

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