🤗 11. 본편 05: smolagents ReAct 도구선택과 실행흐름

이번 편은 Hugging Face Agents Course의 핵심인 “생각(Reason) → 도구 실행(Act) → 관찰(Observe)” 루프를 초보자 관점에서 정확히 잡는 본편이다.
핵심은 어렵지 않다.

에이전트 품질은 모델 크기보다 도구 정의와 성공 판정 기준에서 먼저 올라간다.

• 이전 편: 🤗 10. 실습편 02

한 줄 결론

ReAct 루프를 눈으로 확인 가능한 로그(step)와 명확한 툴 입출력 계약으로 운영하면, 초보자도 “왜 이 답이 나왔는지” 추적 가능한 에이전트를 만들 수 있다.

flowchart TD
  A[사용자 질문] --> B[Agent Reason]
  B --> C{필요 도구 선택}
  C -->|search_web| D[DuckDuckGo 검색]
  C -->|calc_margin| E[마진 계산]
  D --> F[Observation]
  E --> F
  F --> G[다음 step 판단]
  G -->|충분| H[최종 답변]
  G -->|부족| B

---

실습 목표

1. smolagents에서 도구 2개(search_web, calc_margin)를 붙인다.
2. 에이전트가 도구를 선택해 실행하는 ReAct 흐름을 로그로 확인한다.
3. 실무 기준의 성공 판정(정답/근거/재현성)을 체크한다.

준비물

• Python 3.10+
• Hugging Face Access Token (권장)
  • 환경변수명: HF_TOKEN
• 경로: .../Agent/🤗 HF-Agents-Course/downloads

---

1) 환경 준비

• 도구: 터미널, pip
• 입력: 파이썬 가상환경
• 실행명령:

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 --upgrade pip
pip install smolagents duckduckgo-search

• 성공판정:
  • python -c "import smolagents; print('ok')"가 ok 출력

2) 실습 코드 작성

• 도구: 파일 편집기
• 입력: 아래 코드
• 실행명령:

cat > day11_react_toolflow.py <<'PY'
from smolagents import CodeAgent, InferenceClientModel, tool
 
@tool
def calc_margin(revenue: float, cost: float) -> str:
    """매출과 비용으로 마진율(%)을 계산한다."""
    if revenue <= 0:
        return "error: revenue must be > 0"
    margin = ((revenue - cost) / revenue) * 100
    return f"margin={margin:.2f}%"
 
@tool
def search_web(query: str) -> str:
    """웹 검색 결과 요약 문자열을 반환한다."""
    from duckduckgo_search import DDGS
    with DDGS() as ddgs:
        results = list(ddgs.text(query, max_results=3))
    if not results:
        return "검색 결과 없음"
    lines = []
    for i, r in enumerate(results, 1):
        title = r.get("title", "(no title)")
        href = r.get("href", "")
        body = (r.get("body", "") or "")[:120]
        lines.append(f"{i}. {title} | {href} | {body}")
    return "\n".join(lines)
 
model = InferenceClientModel()  # HF_TOKEN 환경변수 사용 권장
agent = CodeAgent(
    tools=[search_web, calc_margin],
    model=model,
    max_steps=6,
)
 
if __name__ == "__main__":
    task = (
        "한국 SaaS 스타트업의 2026년 AI 에이전트 도입 트렌드를 3줄로 요약하고, "
        "월매출 12000000원/월비용 8400000원의 마진율도 함께 계산해줘."
    )
    result = agent.run(task)
    print("\n=== FINAL ===")
    print(result)
PY

• 성공판정:
  • day11_react_toolflow.py 파일 생성 확인

3) 에이전트 실행 + ReAct 단계 확인

• 도구: day11_react_toolflow.py
• 입력: 기본 task 문자열
• 실행명령:

export HF_TOKEN="<your_hf_token>"
python day11_react_toolflow.py

• 성공판정:
  • 출력에 검색 근거(링크/요약) + margin=30.00% 포함
  • 에이전트가 1회 이상 도구 호출한 로그 확인

4) 성공/실패 판정표 (실무형)

• 정상 성공
  • 마진율이 정확히 30.00%
  • 트렌드 요약이 3줄 이내
  • 최소 1개 근거 링크 포함
• 부분 성공
  • 계산은 정확하지만 근거 링크 누락
• 실패
  • 도구 호출 없이 일반론 답변만 출력
  • 계산값 오차(±0.01% 초과)

---

초보자 관점 핵심 설명

• @tool 데코레이터: “이 함수는 에이전트가 호출 가능한 외부 능력”이라고 등록하는 선언이다.
• CodeAgent: 자연어 계획 + 코드 실행 기반으로 tool을 고르는 에이전트.
• max_steps: 무한 루프 방지 안전장치. 운영에선 4~8 사이를 먼저 권장.

실무 적용 포인트

1. 도구 계약을 짧고 명확하게
   • 입력 타입/출력 포맷을 고정하면 에러가 급감한다.
2. 성공 판정 자동화
   • 계산형 태스크는 기대값 비교(assert)로 품질 게이트를 만든다.
3. 근거 강제 프롬프트
   • “최소 1개 URL 포함” 같은 정책을 넣으면 보고서 신뢰도가 올라간다.

트러블슈팅

1. 401 Unauthorized (HF 추론)
   • 원인: HF_TOKEN 누락/권한 문제
   • 해결: 토큰 재발급 후 export HF_TOKEN=...
2. No module named duckduckgo_search
   • 원인: 가상환경 미활성화
   • 해결: source .venv/bin/activate 후 재설치
3. 검색은 되는데 계산이 틀림
   • 원인: revenue/cost 순서 반대로 전달
   • 해결: 함수 시그니처와 호출값 순서 재확인

다음 편 예고

다음 본편에서는 ToolCallingAgent와 정책 가드레일을 결합해, “도구를 쓸 수는 있지만 아무거나 못 쓰게 제한하는” 운영형 패턴으로 확장한다.

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 구조를 작성했으며, 실습 절차/명령어/성공 판정 기준은 사람이 재검토해 발행했다.