🤗 38. HF Agents Course 본편 2 - CodeAgent에 계산기 도구 붙여 안정성 높이기

목표: smolagents의 CodeAgent에 사용자 정의 계산기 도구를 연결해, 단순 수치 작업에서 답변 안정성을 높이는 기본 패턴을 익힌다.

1) 이번 편에서 배우는 것

• 에이전트가 “직접 계산” 대신 “도구 호출”을 하게 만드는 방법
• 초보자도 재현 가능한 최소 프로젝트 구조
• 실무에서 계산/변환류 업무 자동화로 확장하는 포인트

2) 동작 구조 (Mermaid)

flowchart TD
    U[사용자 질문] --> A[CodeAgent]
    A --> D{계산 필요?}
    D -- 예 --> T[CalculatorTool 호출]
    T --> O[계산 결과 반환]
    O --> A
    D -- 아니오 --> R[일반 답변]
    A --> F[최종 출력]

3) 실습 준비

도구

• Python 3.10+
• 터미널
• 가상환경(venv)

입력(테스트 질문)

• "17.5% 부가세를 적용한 128000원의 최종 금액을 계산해줘"
• "(24500 * 3) - 15000 계산해줘"

실행 명령

mkdir -p ~/hf-agents-part2 && cd ~/hf-agents-part2
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install "smolagents[toolkit]"

성공 판정

• 설치 후 에러 없이 프롬프트 복귀
• python -c "import smolagents; print('ok')" 결과가 ok

4) 코드 작성

app.py:

from smolagents import CodeAgent, InferenceClientModel, Tool
 
class CalculatorTool(Tool):
    name = "calculator"
    description = "사칙연산/괄호 계산을 수행합니다. 입력은 수식 문자열이어야 합니다."
    inputs = {
        "expression": {
            "type": "string",
            "description": "예: (24500 * 3) - 15000"
        }
    }
    output_type = "string"
 
    def forward(self, expression: str):
        allowed = "0123456789+-*/(). %"
        if any(ch not in allowed for ch in expression):
            return "오류: 허용되지 않은 문자가 포함되어 있습니다."
 
        try:
            result = eval(expression, {"__builtins__": {}}, {})
            return str(result)
        except Exception as e:
            return f"오류: {e}"
 
 
model = InferenceClientModel()
agent = CodeAgent(
    tools=[CalculatorTool()],
    model=model,
)
 
queries = [
    "17.5% 부가세를 적용한 128000원의 최종 금액을 계산해줘. 필요한 식을 calculator로 계산해.",
    "(24500 * 3) - 15000 계산해줘. calculator를 써서 결과만 알려줘."
]
 
for q in queries:
    print("\n[질문]", q)
    print("[답변]", agent.run(q))

5) 실행

python app.py

성공 판정

• 최소 2개 질문 모두 결과 출력
• 계산 질문에서 도구 호출 후 결과를 반환
• 숫자 결과가 수기로 검산했을 때 일치

6) 초보자용 문제해결 가이드

1. ModuleNotFoundError 발생
   → 가상환경 활성화 여부 확인 후 재실행
2. HF 모델 호출 오류
   → 필요 시 HF_TOKEN 환경변수 설정
3. 수식 파싱 오류
   → 수식에서 한글/쉼표 제거 후 재질문

7) 실무 적용 포인트

• 정산 보조: 세율/할인율 계산 자동화
• 운영 리포트: 반복 KPI 계산을 에이전트+도구로 표준화
• 신뢰성 향상: “말로 계산”보다 “도구 계산”을 강제해 오류 감소

8) 다음 편 예고

다음 본편에서는 검색 도구 + 계산 도구를 함께 사용해, “근거 수집 + 계산 검증”이 가능한 실무형 에이전트로 확장한다.

---

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 구성과 예시 코드를 작성하고, 작성자가 실습 재현성과 링크/표현을 검토해 편집했습니다.