🤗 02. Tool Calling 구조: 도구 설계 + 실행 실습

이번 2편은 에이전트가 실제로 일을 하게 만드는 핵심인 Tool Calling을 다룬다. 목표는 “도구를 붙인다” 수준이 아니라, 실패하지 않는 도구 인터페이스를 설계하고 실행 루프에 안정적으로 연결하는 것이다.

flowchart LR
  A[User Goal] --> B[Planner]
  B --> C[Tool Router]
  C --> D[Tool 1: Search]
  C --> E[Tool 2: Fetch]
  C --> F[Tool 3: Summarize]
  D --> G[Observation]
  E --> G
  F --> G
  G --> H[Final Answer]

0) 30초 요약

• Tool Calling은 “모델이 바깥 세상과 연결되는 입출력 규약”이다.
• 성능보다 먼저 도구 계약(schema), 실패 처리, 검증 규칙을 고정해야 운영이 된다.
• 오늘 산출물: 도구 3개 + 실행 루프 + 실패 대응이 포함된 미니 에이전트 설계/실행본.

1) 왜 Tool Calling이 중요할까

LLM이 아무리 똑똑해도, 최신 데이터·사내 데이터·실행 명령은 스스로 가져오지 못한다. Tool Calling은 이 한계를 넘는 구조다.

핵심 효과:

1. 최신성 확보: 검색/조회 도구로 실시간 정보 반영
2. 재현성 확보: 같은 입력이면 같은 절차로 실행
3. 책임성 확보: 어떤 도구를 왜 호출했는지 추적 가능

2) 도구 설계 원칙 (실무용)

원칙 1) 입력은 좁게, 출력은 명확하게

• 입력 필드는 최소화 (query, limit처럼)
• 출력은 구조화 (title, url, snippet)

원칙 2) 실패를 정상 플로우로 취급

• timeout, empty result, invalid input을 예외가 아니라 분기 처리

원칙 3) 도구별 성공 판정 기준 정의

• Search 성공: 최소 3개 유효 링크
• Fetch 성공: 본문 길이 n자 이상
• Summarize 성공: 금지어/과장어 필터 통과

sequenceDiagram
  participant U as User
  participant A as Agent
  participant S as Search Tool
  participant F as Fetch Tool
  participant M as Summarize Tool

  U->>A: 오늘 AI 뉴스 브리핑
  A->>S: query="AI news", limit=5
  S-->>A: urls[5]
  A->>F: fetch(urls)
  F-->>A: articles
  A->>M: summarize(articles)
  M-->>A: brief
  A-->>U: TOP3 + 근거 링크

3) 실습 A — 도구 계약서 만들기

아래처럼 먼저 도구 스키마부터 적는다.

{
  "tool": "web_search",
  "input": {
    "query": "string",
    "limit": "integer(1~10)"
  },
  "output": [
    {"title": "string", "url": "string", "snippet": "string"}
  ],
  "failure": ["timeout", "empty", "rate_limit"]
}

성공 판정:

• 입력 유효성 검사 존재
• 출력 필드 고정
• 실패 코드 3종 정의

4) 실습 B — Python 미니 루프 구현

4-0) 5분 퀵스타트 (먼저 1회 성공)

1. 문서 하단 실습 파일 다운로드에서 hf-agents-day2-tool-calling.zip을 받는다.
2. 압축 해제 후 폴더로 이동한다.
3. 아래 3줄을 실행한다.

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt && python day2_tool_calling.py

준비

• 도구: Python 3.10+
• 파일: day2_tool_calling.py

실행

python day2_tool_calling.py

실행 결과 예시 (정상/실패)

정상 예시:

{'ok': True, 'count': 3, 'result': [...]} 

실패 예시:

{'ok': False, 'stage': 'search', 'error': 'invalid_query'}

코드

from dataclasses import dataclass
from typing import Dict, List, Optional
 
@dataclass
class ToolResult:
    ok: bool
    data: List[Dict]
    error: Optional[str] = None
 
 
def web_search(query: str, limit: int = 5) -> ToolResult:
    if not query or not query.strip():
        return ToolResult(ok=False, data=[], error="invalid_query")
 
    mock_results = [
        {"title": "AI News A", "url": "https://example.com/a", "snippet": "update A"},
        {"title": "AI News B", "url": "https://example.com/b", "snippet": "update B"},
        {"title": "AI News C", "url": "https://example.com/c", "snippet": "update C"},
        {"title": "AI News D", "url": "https://example.com/d", "snippet": "update D"},
        {"title": "AI News E", "url": "https://example.com/e", "snippet": "update E"},
    ]
    return ToolResult(ok=True, data=mock_results[:limit])
 
 
def validate(items: List[Dict]) -> ToolResult:
    if len(items) < 3:
        return ToolResult(ok=False, data=[], error="insufficient_results")
 
    valid = [x for x in items if x.get("url", "").startswith("https://")]
    if len(valid) < 3:
        return ToolResult(ok=False, data=[], error="invalid_url_format")
 
    return ToolResult(ok=True, data=valid)
 
 
def summarize(items: List[Dict]) -> ToolResult:
    if not items:
        return ToolResult(ok=False, data=[], error="empty_input")
 
    summaries = [
        {
            "summary": f"{item['title']} - 핵심 한 줄 요약",
            "url": item["url"],
        }
        for item in items[:3]
    ]
    return ToolResult(ok=True, data=summaries)
 
 
def run_briefing(query: str):
    searched = web_search(query, limit=5)
    if not searched.ok:
        return {"ok": False, "stage": "search", "error": searched.error}
 
    validated = validate(searched.data)
    if not validated.ok:
        return {"ok": False, "stage": "validate", "error": validated.error}
 
    summarized = summarize(validated.data)
    if not summarized.ok:
        return {"ok": False, "stage": "summarize", "error": summarized.error}
 
    return {"ok": True, "count": len(summarized.data), "result": summarized.data}
 
 
if __name__ == "__main__":
    output = run_briefing("today ai updates")
    print(output)

성공 판정:

• ok=True 결과 출력
• count=3 확인
• 실패 시 stage, error가 출력됨

5) 실습 C — HF/smolagents 연결 포인트

smolagents를 쓸 때도 핵심은 동일하다. 중요한 건 모델이 아니라 툴의 계약 품질이다.

# pip install smolagents
from smolagents import tool
 
@tool
def get_stock_price(symbol: str) -> str:
    """주식 심볼을 입력받아 가격 요약을 반환"""
    # 실제로는 외부 API 호출
    return f"{symbol}: 123.45 USD"

체크포인트:

• 함수 설명(docstring)을 모델이 읽고 선택한다.
• 함수 입력 타입이 애매하면 오호출이 늘어난다.

6) 트러블슈팅 TOP 5

1. 도구 미호출: 프롬프트에 “도구 사용 조건”을 명시하지 않음
2. 오호출: 도구 설명이 모호함
3. 출력 파싱 실패: JSON 스키마 고정 안 함
4. 무한 재시도: retry 상한 부재
5. 사실 오류: 요약 결과 검증 단계 누락

7) 오늘 제출물

### HF Day2 제출물
- 목표 작업:
- 사용 도구(3개):
- 도구 계약서(schema):
- 실패 처리 규칙(최소 3개):
- 실행 결과(성공/실패 로그):
- 개선 포인트(다음 편 반영):

8) 다음 편 예고 (03편)

03편에서는 Tool Calling에 맞는 프롬프트 설계 패턴을 다룬다.

• 시스템/개발자/사용자 역할 분리
• 도구 선택 기준 문장 템플릿
• hallucination 줄이는 출력 가드레일

참고 링크

• https://github.com/huggingface/agents-course
• https://huggingface.co/learn/agents-course
• https://huggingface.co/docs/smolagents

실습 파일 다운로드

• Day2 실습 가이드 README
• day2_tool_calling.py
• requirements.txt
• hf-agents-day2-tool-calling.zip

파일이 브라우저에서 바로 열리면, 우클릭 후 **“다른 이름으로 저장”**을 선택해 다운로드하면 됩니다.

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안 작성 및 구조화를 수행했으며, 최종 공개 전 사람이 검토·보정한다.