LLM Tool Calling - Tool 실행

시리즈: LLM Tool Calling 내부 원리부터 에이전트 직접 구현까지

이 시리즈는 사용자의 자연어 한 줄이 tool 실행으로 바뀌는 내부 처리 과정을 단계별로 해부하고, 최종적으로 오픈소스 모델 + 자체 middleware로 나만의 에이전트를 직접 구현하는 것까지 도달하는 과정이다.

편	내용	핵심
1편	전체 조감도	자연어 → tool 실행까지 5개 레이어의 존재를 확인
2편	Chat Template	JSON이 모델에 직접 들어가지 않는다
3편	Tokenization	모델은 텍스트를 읽지 못한다 - 토큰 ID와 control token
4편	모델 추론	”tool을 쓸까 말까” 판단과 constrained decoding
5편 (본문)	Tool 실행	tool_use를 받은 클라이언트의 실행 루프
6편	Native vs Non-native	같은 기능, 다른 구조 → Middleware
7편	Middleware 만들기	프롬프트 조립 + 출력 파싱 + 실행 루프 직접 구현
8편	오픈소스 모델 로컬 구축	Ollama/vLLM으로 로컬 LLM 서빙
9편	나만의 에이전트	모델 + Middleware = 에이전트 완성

---

• Tool 실행은 모델이 반환한 tool_use 응답을 클라이언트(개발자의 애플리케이션)가 받아 실제 함수를 실행하고, 결과를 다시 모델에 전달하는 과정
• LLM은 tool을 직접 실행하지 않으며, “어떤 tool을, 어떤 인자로 호출해야 하는지”를 기술한 데이터 구조를 반환할 뿐인 구조적 분리
• 이 과정은 한 번으로 끝나지 않고, 모델이 추가 tool call을 요청하면 반복되는 실행 루프

해당 개념이 필요한 이유

• 4편에서 모델이 tool_use: get_weather("Seoul")을 생성하는 과정까지 확인했다. 하지만 이 응답이 사용자의 PC에 도착한 후 누가, 어디서, 어떻게 실제로 실행하는지는 아직 다루지 않았다
• Claude Code에서 파일을 읽거나, MCP server에서 tool을 실행하는 것이 모두 이 단계에서 일어난다
• 이 실행 루프를 이해해야 6편에서 “이 레이어가 없는 모델”의 의미를 정확히 파악할 수 있다

AS-IS

sequenceDiagram
    autonumber
    box 개발자 영역
        participant App as 애플리케이션
    end
    box AI 서비스 영역
        participant LLM as LLM
    end

    App->>LLM: "서울 날씨 알려줘"
    LLM-->>App: tool_use: get_weather("Seoul")
    Note over App: tool을 실행해서 tool_result를<br/>어떻게 모델에 돌려주지?

TO-BE

sequenceDiagram
    autonumber
    box 개발자 영역
        participant App as 애플리케이션
        participant Tool as tool 함수
    end
    box AI 서비스 영역
        participant LLM as LLM
    end

    App->>LLM: "서울 날씨 알려줘"
    LLM-->>App: stop_reason: "tool_use"<br/>name: "get_weather", input: {location: "Seoul"}
    App->>App: tool 이름으로 함수 매핑
    App->>Tool: get_weather("Seoul") 실행
    Tool-->>App: { temperature: "15°C", condition: "맑음" }
    App->>LLM: tool_result 전달
    LLM-->>App: "서울의 현재 날씨는 15°C이며 맑습니다"

tool_use 응답의 구조

4편에서 모델이 생성한 tool_use 응답은 이런 형태다:

{
  "id": "msg_01Aq9w938a90dw8q",
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "text",
      "text": "서울의 날씨를 확인해보겠습니다."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "Seoul", "unit": "celsius" }
    }
  ]
}

핵심 필드 3가지:

• name: 어떤 tool을 호출할지
• id: 이 호출의 고유 식별자 (결과 반환 시 매칭용)
• input: tool에 전달할 인자

stop_reason: "tool_use"가 반환되었다는 것은, 모델이 “나는 여기서 멈추고, 이 tool의 실행 결과를 기다리겠다”는 의미다.

모든 tool이 클라이언트에서 실행되는 것은 아니다

여기서 중요한 구분이 있다. Claude API에서 tool은 실행 위치에 따라 두 종류로 나뉜다:

	Client Tool	Server Tool
실행 위치	개발자의 애플리케이션 (클라이언트)	Anthropic 서버
누가 만드는가	개발자가 직접 정의 + 실행 함수 구현	Anthropic이 미리 구현
예시	get_weather, Read, Bash, MCP tool	web_search, web_fetch
동작 방식	stop_reason: "tool_use" 반환 → 클라이언트가 실행 → tool_result 반환	모델이 호출하면 서버가 자동 실행, 결과가 응답에 포함
개발자 역할	tool 정의 + 실행 함수 구현	API 요청에 tool 타입만 명시

즉, Claude에게 “서울 날씨 검색해줘”라고 하면:

• web_search는 Anthropic 서버에서 실행된다. 개발자가 검색 함수를 구현할 필요 없이, 서버가 알아서 실행하고 결과를 응답에 포함한다.
• get_weather 같은 커스텀 tool은 클라이언트에서 실행된다. 개발자가 실행 함수를 직접 구현해야 한다.

Claude Code에서 Read, Bash, Grep 같은 tool은? 이것들은 client tool이다. Claude Code 애플리케이션이 이 tool들의 실행 함수를 미리 구현해둔 것이다. 사용자가 직접 만든 것은 아니지만, 실행은 사용자의 PC(Claude Code 프로세스)에서 이루어진다.

클라이언트의 tool 실행 루프 (Client Tool)

tool_use 응답을 받은 클라이언트는 다음 과정을 수행한다:

1단계: tool 이름으로 함수 매핑

// tool 이름 → 실제 함수 매핑
const tools: Record<string, (input: any) => Promise<string>> = {
  get_weather: async ({ location, unit }) => {
    const res = await fetch(`https://api.weather.com?city=${location}&unit=${unit}`);
    return JSON.stringify(await res.json());
  },
  get_time: async ({ timezone }) => {
    return new Date().toLocaleString("ko-KR", { timeZone: timezone });
  },
};

2단계: tool 실행

// 응답에서 tool_use 블록 추출
const toolUseBlock = response.content.find((block) => block.type === "tool_use");
 
// 매핑된 함수 실행
const toolFunction = tools[toolUseBlock.name];
const result = await toolFunction(toolUseBlock.input);

3단계: tool_result를 모델에 반환

// tool 실행 결과를 다시 모델에 전달
const followUp = await anthropic.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  tools: [/* 같은 tool 정의 */],
  messages: [
    // 기존 대화 이력
    { role: "user", content: "서울 날씨 알려줘" },
    // 모델의 tool_use 응답 (그대로 포함)
    { role: "assistant", content: response.content },
    // tool 실행 결과
    {
      role: "user",
      content: [{
        type: "tool_result",
        tool_use_id: toolUseBlock.id,  // tool_use의 id와 매칭
        content: result,
      }],
    },
  ],
});
// followUp → "서울의 현재 날씨는 15°C이며 맑습니다"

tool_use_id로 어떤 tool call에 대한 결과인지 매칭한다. 3편에서 본 Mistral V3의 call_id와 동일한 역할이다.

멀티턴 Tool Calling

tool 실행은 한 번으로 끝나지 않을 수 있다. 모델이 결과를 받은 후 추가 tool call을 요청할 수 있다:

sequenceDiagram
    autonumber
    box 개발자 영역
        participant App as 애플리케이션
    end
    box AI 서비스 영역
        participant LLM as LLM
    end

    App->>LLM: "서울과 도쿄 날씨 비교해줘"
    LLM-->>App: tool_use: get_weather("Seoul")
    Note over App: get_weather("Seoul") 실행
    App->>LLM: tool_result: "15°C, 맑음"
    LLM-->>App: tool_use: get_weather("Tokyo")
    Note over App: get_weather("Tokyo") 실행
    App->>LLM: tool_result: "22°C, 흐림"
    LLM-->>App: stop_reason: "end_turn"<br/>"서울은 15°C, 도쿄는 22°C. 도쿄가 7도 더 따뜻합니다."

이 루프가 반복되는 조건:

• stop_reason === "tool_use" → tool 실행 후 결과를 다시 전달
• stop_reason === "end_turn" → 모델이 최종 응답을 완료, 루프 종료

SDK가 자동으로 처리하는 실행 루프

위의 수동 루프를 매번 작성하는 것은 번거롭다. Anthropic SDK와 Vercel AI SDK는 이 과정을 자동화한다.

Anthropic SDK - Tool Runner (beta)

import { Anthropic } from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
 
const anthropic = new Anthropic();
 
// tool 정의 + 실행 함수를 함께 등록
const getWeatherTool = betaZodTool({
  name: "get_weather",
  description: "Get the current weather in a given location",
  inputSchema: z.object({
    location: z.string().describe("City name"),
    unit: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  }),
  run: async (input) => {
    // 실제 API 호출
    return JSON.stringify({ temperature: "15°C", condition: "Sunny" });
  },
});
 
// toolRunner가 실행 루프를 자동 처리
const runner = anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-6",
  max_tokens: 1024,
  tools: [getWeatherTool],
  messages: [{ role: "user", content: "서울 날씨 알려줘" }],
});
 
for await (const message of runner) {
  console.log(message.content[0].text);
}

Vercel AI SDK - generateText

import { generateText, tool } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";
import { stepCountIs } from "ai";
 
const result = await generateText({
  model: anthropic("claude-opus-4-6"),
  tools: {
    weather: tool({
      description: "Get the weather in a location",
      parameters: z.object({ location: z.string() }),
      execute: async ({ location }) => ({
        location,
        temperature: 15,
        condition: "맑음",
      }),
    }),
  },
  stopWhen: stepCountIs(5),  // 최대 5단계까지 자동 반복
  prompt: "서울 날씨 알려줘",
});

두 SDK 모두 핵심은 같다: tool 정의와 실행 함수를 함께 등록하면, stop_reason: "tool_use" 감지 → 함수 실행 → 결과 반환 → 추가 호출 확인의 루프를 자동으로 처리한다.

MCP Server에서의 Tool 실행

Claude Code나 Cursor 같은 클라이언트에서 MCP server를 사용하면, tool 실행이 한 단계 더 위임된다:

sequenceDiagram
    autonumber
    box 클라이언트 영역
        participant Client as Claude Code
    end
    box MCP Server 영역
        participant MCP as MCP Server
        participant Tool as tool 함수
    end
    box AI 서비스 영역
        participant LLM as LLM
    end

    Client->>LLM: tools 정의 + 사용자 질문
    LLM-->>Client: tool_use: get_weather("Seoul")
    Client->>MCP: call_tool("get_weather", {location: "Seoul"})
    MCP->>Tool: 실제 함수 실행
    Tool-->>MCP: 결과
    MCP-->>Client: tool_result
    Client->>LLM: tool_result 전달
    LLM-->>Client: 최종 응답

클라이언트(Claude Code)는 tool을 직접 실행하지 않고, MCP server에 실행을 위임한다. 이것이 MCP의 핵심 가치다: tool 정의와 실행을 외부 서버로 분리하여, 클라이언트는 프로토콜만 알면 된다.

다음 편: 이 모든 레이어가 항상 있는 건가?

1~5편에 걸쳐 자연어 → Chat Template → Tokenization → 모델 추론 → Tool 실행의 전체 파이프라인을 확인했다. Claude, GPT 같은 상용 모델 API를 사용하면 이 모든 레이어가 내장되어 있다.

하지만 오픈소스 모델(Llama, Gemma 등)을 로컬에서 실행하면 어떻게 될까? 이 레이어들이 전부 또는 일부 존재하지 않는다. 그러면 tool calling을 어떻게 구현할까?

다음 편에서 Native tool calling 모델과 Non-native 모델의 구조적 차이를 비교한다.

참고 문서

• Anthropic - Tool Use Implementation - tool_result 반환, Tool Runner, 멀티턴 tool calling
• Vercel AI SDK - Tool Calling - generateText의 자동 tool 실행 루프, stopWhen
• MCP - Build an MCP Client - MCP 프로토콜에서의 tool 실행 위임