3 분 소요

한 줄 요약: 툴 콜링(Tool Calling)이란, LLM이 스스로 판단하여 외부 함수·API·도구를 구조화된 형식으로 호출하고 그 결과를 응답에 통합하는 메커니즘이다.

1. 툴 콜링(Tool Calling)이란 무엇인가?

LLM은 본래 “텍스트 → 텍스트” 변환기입니다. 아무리 뛰어난 모델이라도 실시간 날씨를 조회하거나, 데이터베이스에서 레코드를 가져오거나, 코드를 실제로 실행하는 일은 혼자 할 수 없었습니다.

툴 콜링은 이 한계를 뛰어넘는 핵심 인터페이스입니다. 모델이 “이 작업은 외부 도구가 필요하다”고 판단하면, 자연어 대신 구조화된 JSON 형태의 호출 명세를 생성하고, 실행 환경(하네스)이 이를 받아 실제 함수를 실행한 뒤 결과를 다시 모델에 돌려줍니다.

공식 정의 (Anthropic Docs): “Tool use (function calling) allows Claude to interact with external services and databases, and to take actions in the real world.” — Anthropic Tool Use Overview

쉽게 말해, LLM에게 “스마트폰 앱”을 쥐여 준 것과 같습니다. 직접 계산기가 되는 것이 아니라, 계산기 앱을 열어 결과를 받아옵니다.

2. 핵심 개념 이해하기

2.1 툴 콜링의 3단계 흐름

사용자 메시지
      │
      ▼
┌─────────────┐    ① 도구 목록 제공
│   LLM       │◄──── [tool_definitions]
│  (Claude)   │
└──────┬──────┘
       │ ② tool_use 블록 생성
       │    { name: "get_weather", input: { city: "Seoul" } }
       ▼
┌─────────────┐
│  실행 환경  │  ③ 실제 함수 실행 → 결과 반환
│  (Harness)  │──────────────────────────────►
└─────────────┘
       │ ④ tool_result 제공
       ▼
┌─────────────┐
│   LLM       │  ⑤ 최종 응답 생성
│  (Claude)   │──────────────────────────────► 사용자 응답
└─────────────┘

2.2 구성 요소

구성 요소 역할 예시
Tool Definition 도구 이름·설명·파라미터 스키마 정의 { name: "search_web", description: "...", input_schema: {...} }
Tool Use Block 모델이 생성하는 호출 명세 { type: "tool_use", name: "search_web", input: { query: "..." } }
Tool Result 실행 결과를 모델에 반환 { type: "tool_result", content: "검색 결과..." }
Orchestrator 도구를 실제로 실행하는 코드 Python 함수, API 클라이언트 등

2.3 stop_reason: “tool_use”

모델이 도구 호출이 필요하다고 판단하면 stop_reason이 "tool_use"로 설정됩니다. 이 신호를 받은 실행 환경이 해당 도구를 실행하고 결과를 다시 대화에 주입하는 방식으로 루프가 구성됩니다.

2.4 병렬 툴 콜링 (Parallel Tool Use)

단일 응답에서 여러 도구를 동시에 호출할 수 있습니다. 예를 들어 “서울 날씨와 뉴욕 날씨를 동시에 조회”하는 경우, 모델은 두 개의 tool_use 블록을 한 번에 생성합니다.

3. 실무 적용 예시

3.1 날씨 조회 도구 정의 및 호출

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "주어진 도시의 현재 날씨를 조회합니다.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "날씨를 조회할 도시명 (예: Seoul, Tokyo)"
                }
            },
            "required": ["city"]
        }
    }
]

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "서울 날씨가 어때?"}]
)

# 모델이 tool_use를 반환하면 실제 함수 실행
if response.stop_reason == "tool_use":
    for block in response.content:
        if block.type == "tool_use":
            print(f"호출 도구: {block.name}")
            print(f"파라미터: {block.input}")

3.2 tool_result 주입 패턴

def run_tool(tool_name: str, tool_input: dict) -> str:
    if tool_name == "get_weather":
        return f"{tool_input['city']} 현재 기온: 27°C, 맑음"
    return "알 수 없는 도구"

# tool_result를 messages에 추가해 모델에 재전송
messages = [
    {"role": "user", "content": "서울 날씨가 어때?"},
    {"role": "assistant", "content": response.content},
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": run_tool(block.name, block.input)
            }
        ]
    }
]

final_response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=messages
)
print(final_response.content[0].text)

4. 툴 콜링 vs 유사 개념 비교

구분 툴 콜링 (Tool Calling) 함수 호출 (Function Calling) MCP (Model Context Protocol)
정의 LLM이 외부 도구를 호출하는 범용 메커니즘 OpenAI가 명명한 동일 개념의 초기 용어 표준화된 툴 콜링 프로토콜 규격
범위 모든 AI 플랫폼에서 사용 주로 OpenAI 생태계에서 사용 서버-클라이언트 구조로 확장
표준화 각 공급사마다 스키마 상이 OpenAI 스키마 기준 Anthropic 주도 오픈 표준
호출 방식 API 파라미터 (tools) API 파라미터 (functions) MCP 서버를 통한 도구 노출
관계 상위 개념 툴 콜링의 하위 구현 툴 콜링의 표준화된 확장판

핵심 차이: Function Calling은 툴 콜링의 특정 구현 명칭이고, MCP는 툴 콜링을 네트워크 수준에서 표준화한 프로토콜입니다. 툴 콜링이 가장 넓은 개념입니다.

5. 마치며

툴 콜링은 LLM을 단순한 텍스트 생성기에서 행동하는 에이전트로 변환시키는 핵심 인터페이스입니다. 도구 정의 → 모델의 tool_use 생성 → 실행 환경의 함수 실행 → tool_result 주입이라는 루프를 이해하면, 에이전틱 AI 시스템의 절반을 이해한 것입니다.

실무에서는 도구 설명(description)을 명확하게 작성하는 것이 가장 중요합니다. 모델은 설명을 보고 도구를 선택하기 때문에, 모호한 설명은 잘못된 도구 선택으로 이어집니다.

다음에 읽으면 좋을 관련 용어: 함수 호출 (Function Calling), MCP (Model Context Protocol), 에이전틱 AI (Agentic AI), 하네스 엔지니어링 (Harness Engineering)

참고 자료

함께 읽으면 좋은 용어

이 개념과 함께 알아두면 이해가 깊어지는 관련 용어들입니다.

Function Calling MCP Agentic AI LLM Harness Engineering

댓글 남기기

참고