🤗 05. HF Agents Course 본편 4 - ToolCallingAgent로 신뢰 가능한 워크플로우 만들기

이번 편에서는 ToolCallingAgent를 사용해 “입력 → 도구 실행 → 결과 검증” 흐름을 안정적으로 만드는 법을 다룹니다. 목표는 초보자도 재현 가능한 최소 예제를 만든 뒤, 실무형 체크포인트(로그/오류/성공판정)를 붙이는 것입니다.

1) 왜 ToolCallingAgent를 쓰나?

• LLM이 직접 답만 생성하면, 외부 데이터 접근/계산/검증이 약합니다.
• ToolCallingAgent는 필요한 순간 툴을 호출해 행동 가능한 답을 만듭니다.
• 핵심은 “좋은 프롬프트”보다 좋은 실행 루프(로그, 판정, 실패 복구) 입니다.

2) 전체 흐름

flowchart TD
  A[사용자 질의] --> B[ToolCallingAgent 계획]
  B --> C[도구 호출: search_weather]
  C --> D[도구 결과 수신]
  D --> E[결과 검증: 필수 필드/단위]
  E --> F[최종 답변 생성]
  E -->|검증 실패| G[재시도 또는 오류 메시지]

3) 실습: 서울 날씨 요약 에이전트

준비 도구

• Python 3.10+
• 패키지: smolagents, python-dotenv
• 모델 키(예: Hugging Face Inference 또는 OpenAI 호환 키)

폴더/파일

mkdir -p hf-agent-lesson4 && cd hf-agent-lesson4
python3 -m venv .venv
source .venv/bin/activate
pip install -U smolagents python-dotenv

.env

HF_TOKEN=your_hf_token

app.py

from dotenv import load_dotenv
from smolagents import ToolCallingAgent, InferenceClientModel, tool
import requests
 
load_dotenv()
 
@tool
def search_weather(city: str) -> str:
    """도시 이름을 받아 현재 기온/날씨를 짧게 반환"""
    # 데모용 공개 엔드포인트 (예시)
    url = f"https://wttr.in/{city}?format=j1"
    r = requests.get(url, timeout=10)
    r.raise_for_status()
    data = r.json()
    current = data["current_condition"][0]
    temp_c = current.get("temp_C", "N/A")
    desc = current.get("weatherDesc", [{"value": "N/A"}])[0]["value"]
    return f"{city} 현재 {temp_c}°C, {desc}"
 
model = InferenceClientModel()
agent = ToolCallingAgent(
    tools=[search_weather],
    model=model,
    max_steps=4,
)
 
query = "서울 오늘 날씨를 한 줄로 요약해줘"
result = agent.run(query)
print(result)

실행 명령

python app.py

성공 판정

아래 3개를 만족하면 성공입니다.

1. 실행 중 도구 호출 흔적이 로그에 보인다. (search_weather)
2. 출력에 도시명/기온/상태가 포함된다. (예: 서울 현재 22°C, Partly cloudy)
3. 예외 없이 프로세스가 종료된다. (exit code 0)

4) 초보자 실수와 빠른 복구

• API/토큰 누락: .env와 쉘 환경변수 중복 확인
• 도구 타임아웃: requests.get(..., timeout=10) 유지
• 출력 포맷 흔들림: 도구 반환 문자열을 고정 템플릿으로 제한

5) 실무 적용 포인트

• 툴 함수는 “짧고 결정적(deterministic)”으로 설계
• 에이전트 응답 신뢰성은 모델보다 도구 스키마 + 검증 규칙이 좌우
• 운영 시 최소 3개 로그를 남기세요: 입력, 툴 결과, 최종 응답

6) 다음 편 예고

다음 본편에서는 ToolCallingAgent에 다중 도구 라우팅(검색+계산+포맷터) 을 붙여 업무 자동화 템플릿으로 확장합니다.

---

생성형 AI 활용 고지

이 문서는 생성형 AI로 초안을 만들고, Hugging Face 공식 자료(코스/문서) 기준으로 사실관계와 실습 단계를 검토·보정했습니다.