🤗 39. HF Agents Course 본편 1 - 에이전트의 핵심 루프와 첫 smolagents 실행

목표: HF Agents Course 본편 1의 핵심인 에이전트 루프(Thought → Action → Observation) 를 이해하고, smolagents로 첫 실행 가능한 에이전트를 직접 띄운다.

Hugging Face Agents Course는 Unit 1에서 에이전트의 기본 개념을, Unit 2.1에서 smolagents 같은 프레임워크 실습을 연결합니다. 초보자라면 이 둘을 한 번에 묶어서 이해하는 편이 훨씬 쉽습니다.

1. 이번 편에서 꼭 잡아야 할 개념

에이전트는 그냥 답만 생성하는 챗봇이 아니라, 필요하면 도구를 쓰고, 결과를 보고, 다시 판단하는 실행 주체입니다.

핵심 구성은 4개입니다.

• Thought: 지금 무엇을 해야 하는지 판단
• Action: 도구 실행
• Observation: 도구 결과 확인
• Final Answer: 최종 응답 정리

즉, “생각만 하는 모델”이 아니라 “생각하고 행동하는 모델”로 보는 것이 HF Agents Course의 출발점입니다.

2. 전체 흐름 한눈에 보기

flowchart LR
    U[사용자 요청] --> T[Thought: 문제를 쪼갬]
    T --> Q{도구가 필요한가?}
    Q -- 아니오 --> A[바로 답변 작성]
    Q -- 예 --> X[Action: 검색/계산 등 도구 실행]
    X --> O[Observation: 결과 확인]
    O --> T
    A --> F[Final Answer]

실무에서는 이 루프 덕분에 다음이 가능해집니다.

• 최신 정보가 필요할 때 검색 도구 사용
• 계산 실수를 줄이기 위해 코드 실행 사용
• 여러 단계 작업을 순서대로 처리

3. 실습 목표

이번 실습에서는 아래 2가지를 확인합니다.

1. smolagents가 정상 설치되는지
2. 검색 도구가 붙은 CodeAgent가 실제로 응답하는지

4. 실습 준비

준비 도구

• Python 3.10 이상
• 터미널
• Hugging Face 계정(권장)
• 인터넷 연결

실습 입력

아래 질문으로 실행합니다.

• Hugging Face Agents Course의 목적 3가지를 한국어로 요약해줘. 필요하면 검색을 사용해.

작업 폴더 만들기

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

가상환경 및 패키지 설치

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

성공 판정

아래 명령이 ok를 출력하면 준비 완료입니다.

python -c "import smolagents; print('ok')"

5. 첫 smolagents 에이전트 만들기

app.py 파일을 만들고 아래 코드를 넣습니다.

from smolagents import CodeAgent, DuckDuckGoSearchTool, InferenceClientModel
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
)
 
query = "Hugging Face Agents Course의 목적 3가지를 한국어로 요약해줘. 필요하면 검색을 사용해."
result = agent.run(query)
print(result)

코드 설명

• InferenceClientModel() : Hugging Face Inference 기반 모델 연결
• DuckDuckGoSearchTool() : 웹 검색 도구 추가
• CodeAgent(...) : 필요 시 코드/도구를 조합해 문제 해결
• agent.run(query) : 실제 실행

6. 실행 명령

python app.py

성공 판정

아래 조건을 만족하면 성공입니다.

• 에러 없이 실행 완료
• 답변에 코스 목적이 최소 3개 항목으로 정리됨
• 필요 시 검색 도구를 사용한 흔적이 로그에 나타남

7. 자주 막히는 문제와 해결

1) ModuleNotFoundError

원인: 가상환경이 꺼져 있거나 설치가 안 됨

해결:

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

2) 모델 호출 관련 인증 이슈

원인: 환경에 따라 Hugging Face 토큰이 필요할 수 있음

해결 예시:

export HF_TOKEN=hf_xxx

3) 검색 품질이 애매함

원인: 질문이 너무 넓음

해결: 요청을 더 구체화합니다.

• 예: Unit 1 기준으로 핵심 학습 목표 3가지만 정리해줘.

8. 초보자 기준으로 이해해야 할 포인트

여기서 중요한 건 “정답 품질”보다 작동 구조를 눈으로 확인하는 것입니다.

특히 첫 실습에서는 아래를 꼭 체크하세요.

• 모델이 혼자 답하는지
• 도구가 필요한 순간에 검색을 호출하는지
• 검색 결과를 보고 최종 답을 다시 정리하는지

이 3개를 이해하면 이후 계산기, 코드 실행, 멀티툴 연결로 자연스럽게 넘어갈 수 있습니다.

9. 실무 적용 포인트

콘텐츠 리서치 자동화

초안 작성을 시작하기 전에 에이전트가 관련 자료를 먼저 모으게 할 수 있습니다.

운영 매뉴얼 보조

문서 검색 도구를 붙이면 사내 위키나 제품 문서를 먼저 찾고 요약하게 만들 수 있습니다.

반복 질문 대응

매번 비슷한 질문을 받는 팀이라면 검색 + 요약형 에이전트로 1차 응답 시간을 줄일 수 있습니다.

10. 이번 편 한 줄 정리

HF Agents Course 본편 1의 핵심은 어렵지 않습니다.
에이전트는 “생각 → 도구 실행 → 결과 확인 → 답변” 루프를 도는 시스템이고, smolagents는 그 루프를 가장 짧게 체험하기 좋은 출발점입니다.

11. 다음 편 예고

다음 본편에서는 CodeAgent에 계산기 같은 명시적 도구를 붙여, “말은 그럴듯하지만 계산은 틀리는” 문제를 어떻게 줄이는지 이어서 다룹니다.

---

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 구조와 예시 코드를 작성했고, 실제 공개 자료(Hugging Face Agents Course 저장소/코스 페이지/smolagents 문서)를 기준으로 사람이 재현 단계, 설명, 링크 구성을 검토해 편집했습니다.