🤗 37. HF Agents Course 실습편 1 - 미니 프로젝트로 ReAct 에이전트 만들기

이번 실습은 smolagents로 “질문 → 웹 검색 → 계산 → 답변” 흐름을 갖는 미니 에이전트를 직접 실행해보는 1편입니다.

• 우선 참고: agents-course GitHub
• 학습 페이지: HF Agents Course
• 구현 문서: smolagents Docs

실습 목표

• ReAct 스타일 도구 호출 흐름 이해
• 최소 2개 도구를 가진 에이전트 실행
• 실패 로그를 읽고 복구하는 습관 만들기

아키텍처(요약)

flowchart TD
    U[사용자 질문] --> A[CodeAgent]
    A --> T1[DuckDuckGoSearchTool]
    A --> T2[Python 실행 도구]
    T1 --> A
    T2 --> A
    A --> R[최종 답변]

준비물

• Python 3.10+
• 가상환경(venv)
• 인터넷 연결
• (선택) Hugging Face 토큰

Step 1) 작업 폴더 및 환경 준비

입력

mkdir -p ~/tmp/hf-agents-lab01 && cd ~/tmp/hf-agents-lab01
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install smolagents duckduckgo-search

성공 판정

• pip show smolagents가 정상 출력된다.

Step 2) 에이전트 코드 작성

lab01_agent.py 파일 생성:

from smolagents import CodeAgent, DuckDuckGoSearchTool
 
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model="Qwen/Qwen2.5-Coder-32B-Instruct",
)
 
question = "서울과 도쿄의 현재 시차를 확인하고, 도쿄가 서울보다 몇 시간 빠른지 한 줄로 설명해줘."
result = agent.run(question)
print(result)

모델 문자열은 환경에 따라 변경될 수 있습니다. 로컬/원격 설정에 맞춰 대체하세요.

Step 3) 실행

실행 명령

python lab01_agent.py

성공 판정

• 콘솔에 “도쿄가 서울보다 X시간 빠름/같음” 형태의 결과가 출력된다.
• 실행 중 검색 도구 호출 로그(Thought/Action 계열)가 보인다.

Step 4) 검증 질문 2개 더 실행

질문을 아래로 바꿔 2회 추가 실행:

1. “대한민국 기준 올해가 윤년인지 계산 근거와 함께 알려줘.”
2. “100달러를 원화로 대략 환산할 때 주의할 점 2가지를 말해줘.”

성공 판정

• 도구 호출 후, 근거가 포함된 답이 나온다.
• 계산/검색이 필요한 질문에서 단답만 내지 않는다.

트러블슈팅 (자주 막히는 4가지)

1. ModuleNotFoundError: smolagents

• 원인: venv 미활성화 또는 설치 실패
• 해결:
  • source .venv/bin/activate
  • pip install smolagents

2. 모델 호출 실패(권한/엔드포인트 오류)

• 원인: 현재 환경에서 해당 모델 접근 불가
• 해결:
  • smolagents 문서 기준으로 사용 가능한 모델로 교체
  • 필요한 경우 HF 토큰 설정 후 재실행

3. 검색 도구 타임아웃/빈 결과

• 원인: 네트워크 이슈, 질의가 너무 모호함
• 해결:
  • 질문을 구체화(시간대/국가/단위 명시)
  • 재시도 전 네트워크 확인

4. 한국어 질문에서 장황하거나 틀린 단정

• 원인: 프롬프트에 출력 형식 제약 없음
• 해결:
  • 질문 끝에 형식 제약 추가
  • 예: “최대 3문장, 불확실하면 불확실하다고 명시”

체크리스트

• 가상환경 생성/활성화 완료
• smolagents 설치 완료
• 에이전트 1회 이상 실행 성공
• 검증 질문 2개 추가 실행
• 트러블슈팅 1개 이상 직접 복구

다음 편 예고

2편에서는 커스텀 툴(예: 환율 API 래퍼) 을 붙여, 검색+계산+외부 데이터 결합형 에이전트로 확장합니다.

---

AI 활용 고지: 본 문서는 생성형 AI로 초안 구조를 만들고, 실습 명령·검증 기준·트러블슈팅을 사람이 검토/수정해 게시했습니다.