🤗 13. 실습편 03: 멀티툴 리서치 어시스턴트 미니 프로젝트 핸즈온

이번 편은 smolagents 기반 멀티툴 리서치 어시스턴트를 만드는 실습이다.
핵심은 “질의 → 로컬 지식 검색 → 체크리스트 생성 → FINAL: 계약 출력” 흐름을 고정해, 팀 자동화에 바로 연결 가능한 결과 형태를 만드는 것이다.

• 이전 편: 🤗 12. 본편 06

한 줄 결론

도구 출력 계약(FINAL:)을 먼저 고정하고, 온라인(smolagents)·오프라인(fallback) 실행 경로를 함께 두면 실습 재현성과 운영 안정성을 동시에 확보할 수 있다.

flowchart LR
  A[사용자 질의] --> B[search_docs 툴]
  B --> C[build_checklist 툴]
  C --> D[CodeAgent 추론]
  D --> E[FINAL 계약 문자열]
  E --> F[single/eval 파서]
  F --> G[PASS/FAIL 판정]

---

실습 목표

• smolagents CodeAgent에 커스텀 도구 2개를 연결한다.
• 출력 포맷을 FINAL: summary=... | checklist=... | verdict=...로 고정한다.
• selfcheck → single → eval 순서로 재현 가능한 검증 루프를 만든다.

실습 파일

• day13_multitool_research_handson.py
• sample_tasks_day13.json

---

1) 환경 준비

• 도구: Python 3.10+, 터미널, 가상환경
• 입력: requirements.txt (+ 온라인 모드면 API 키)
• 실행명령:

cd "/home/tw2/Documents/n8n/data/shared/syn/8.quartz/Agent/🤗 HF-Agents-Course/downloads"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

• 성공판정:
  • (.venv) 프롬프트가 보인다.
  • 설치가 에러 없이 끝난다.

2) 셀프체크 실행 (도구 단위 검증)

• 도구: day13_multitool_research_handson.py
• 입력: 내장 테스트 질의(smolagents tool calling 평가)
• 실행명령:

python3 day13_multitool_research_handson.py --mode selfcheck

• 성공판정:
  • 출력 JSON에 "selfcheck_ok": true

3) 단일 실행 (오프라인 재현 경로)

• 도구: day13_multitool_research_handson.py
• 입력: 질의 1개
• 실행명령:

python3 day13_multitool_research_handson.py \
  --mode single \
  --offline \
  --query "HF Agents Course에서 tool calling 학습 포인트 정리"

• 성공판정:
  • verdict가 READY 또는 NEEDS_REVIEW
  • summary, checklist 필드가 비어 있지 않다.

4) 단일 실행 (온라인 smolagents 경로)

• 도구: day13_multitool_research_handson.py, smolagents, LLM API 키
• 입력:
  • OPENAI_API_KEY (예시)
  • 모델: openai/gpt-4o-mini (기본)
• 실행명령:

export OPENAI_API_KEY="<your-key>"
python3 day13_multitool_research_handson.py \
  --mode single \
  --model openai/gpt-4o-mini \
  --query "smolagents에서 CodeAgent와 ToolCallingAgent 차이를 요약해줘"

• 성공판정:
  • 결과 JSON에 summary/checklist/verdict가 파싱된다.
  • verdict가 READY 또는 NEEDS_REVIEW이다.

5) 배치 평가 (재현성 점검)

• 도구: sample_tasks_day13.json
• 입력: 샘플 태스크 3개
• 실행명령:

# 오프라인 평가
python3 day13_multitool_research_handson.py --mode eval --offline --input sample_tasks_day13.json
 
# 온라인 평가
python3 day13_multitool_research_handson.py --mode eval --input sample_tasks_day13.json

• 성공판정:
  • pass = true 또는 score >= 0.66

---

코드에서 꼭 볼 포인트

1. search_course_docs()
   • 질의 기반 문서 스니펫 검색(로컬 지식베이스)
2. make_checklist()
   • 요약 결과를 실행 가능한 점검 항목으로 변환
3. parse_final_block()
   • FINAL: 계약 문자열을 구조화 JSON으로 파싱
4. offline_agent() / online_agent()
   • 운영 장애 대비 이중 실행 경로

---

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

1. ModuleNotFoundError: smolagents

   • 원인: 가상환경 미활성화 또는 의존성 미설치
   • 해결: source .venv/bin/activate 후 pip install -r requirements.txt

2. OPENAI_API_KEY 누락으로 온라인 실행 실패

   • 원인: LiteLLMModel 인증 정보 미설정
   • 해결: export OPENAI_API_KEY="..." 후 재실행 (혹은 --offline으로 먼저 검증)

3. input JSON root must be list

   • 원인: sample_tasks_day13.json 루트를 객체 {}로 저장
   • 해결: 루트를 배열 [] 형식으로 유지

4. FINAL: 파싱 실패 (verdict=PARSE_ERROR)

   • 원인: 모델 출력이 계약 포맷을 벗어남
   • 해결: 프롬프트의 출력 형식을 더 엄격히 고정하고, 필요 시 재시도 로직 추가

5. 한글/이모지 경로에서 파일 찾기 실패

   • 원인: 경로 인용 누락
   • 해결: 경로 전체를 큰따옴표로 감싸 실행

---

체크리스트

• selfcheck_ok=true 확인
• single --offline 결과에서 summary/checklist/verdict 확인
• single(온라인)에서 동일 계약 파싱 확인
• eval 결과 score 기록
• 팀 기준으로 required_keyword 1개 이상 커스터마이즈

참고 링크 (우선순위)

1. https://github.com/huggingface/agents-course
2. https://huggingface.co/learn/agents-course
3. https://huggingface.co/docs/smolagents

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 작성·구조화·예제 코드 정리를 수행했으며, 최종 발행 전 사람이 재현 절차와 링크를 점검했다.