LLM Tool Calling Pipeline

시리즈: 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 = 에이전트 완성

---

• LLM Tool Calling 파이프라인은 사용자의 자연어 한 줄이 실제 함수 실행으로 바뀌는 전체 내부 처리 과정
• LLM이 함수를 직접 실행하지 않고, 호출을 기술하는 데이터 구조를 생성하면 별도 프로그램이 실행하는 구조적 분리
• API JSON 통신 이면에 숨어있는 5개 처리 레이어(Chat Template, Tokenization, 모델 추론, Constrained Decoding, 출력 파싱)의 조감도

해당 개념이 필요한 이유

• 개발자가 MCP server에 tool을 등록하면 LLM이 알아서 골라 쓴다. 하지만 어떻게 고르는지는 블랙박스다
• Claude Code에서 파일을 읽을 때 Read, Bash, Grep 중 하나를 선택하는 판단 과정이 내부에서 일어나지만 보이지 않는다
• 이 블랙박스를 열어야 tool 정의를 잘 작성하고, 디버깅할 수 있고, 나아가 자체 에이전트를 만들 수 있다

AS-IS

sequenceDiagram
    autonumber
    box 사용자 영역
        participant User as 사용자
    end
    box AI 서비스 영역 (Claude, GPT 등)
        participant API as API 서버
        participant LLM as LLM
    end

    User->>API: "서울 날씨 알려줘" + tools 정의 (JSON)
    Note over API,LLM: ??? 블랙박스 ???
    LLM-->>API: tool_use: get_weather("Seoul")
    API-->>User: tool call 결과 (JSON)

TO-BE

sequenceDiagram
    autonumber
    box 사용자 영역
        participant User as 사용자
    end
    box AI 서비스 영역 (Claude, GPT 등)
        participant API as API 서버
        participant CT as Chat Template
        participant TK as Tokenizer
        participant Model as 모델 추론
        participant Parser as 출력 파서
    end

    User->>API: "서울 날씨 알려줘" + tools 정의 (JSON)
    API->>CT: JSON → 프롬프트 텍스트 조립
    CT->>TK: 텍스트 → 토큰 ID 시퀀스
    TK->>Model: 토큰 시퀀스 입력
    Model->>Model: 다음 토큰 예측 반복
    Model->>Parser: tool_call 패턴 토큰 생성
    Parser->>API: 토큰 → structured JSON 변환
    API-->>User: tool_use: get_weather("Seoul")

개발자가 매일 경험하는 tool calling

우리는 이미 tool calling을 매일 사용하고 있다.

Claude Code에서 파일을 읽을 때:

// Claude Code가 내부적으로 하는 일
const response = await anthropic.messages.create({
  model: "claude-opus-4-6",
  tools: [
    { name: "Read", description: "Read a file", input_schema: { ... } },
    { name: "Bash", description: "Execute a bash command", input_schema: { ... } },
    { name: "Grep", description: "Search file contents", input_schema: { ... } },
  ],
  messages: [{ role: "user", content: "src/index.ts 파일 내용 보여줘" }],
});
// response.content → { type: "tool_use", name: "Read", input: { file_path: "src/index.ts" } }

MCP server에서 tool을 등록할 때:

// MCP server에서 tool 정의를 가져와 Claude API에 전달
const mcpTools = await mcpClient.listTools();
const claudeTools = mcpTools.tools.map((tool) => ({
  name: tool.name,
  description: tool.description ?? "",
  input_schema: tool.inputSchema,  // inputSchema → input_schema 변환
}));

두 경우 모두 동일한 파이프라인을 탄다. tool이 어디서 정의되었든(코드 내장, MCP server, 외부 API), LLM 내부의 처리 과정은 같다.

블랙박스 안의 5개 레이어

API JSON이 모델에 들어가서 tool call이 나오기까지, 내부에는 5개의 처리 레이어가 존재한다.

flowchart LR
    A[Chat Template] --> B[Tokenization] --> C[모델 추론] --> D[Constrained Decoding] --> E[출력 파싱]

레이어	하는 일	편
Chat Template	API JSON을 모델이 이해할 수 있는 하나의 긴 텍스트로 조립	2편
Tokenization	텍스트를 숫자(토큰 ID)로 변환. 모델은 텍스트를 직접 읽지 못한다	3편
모델 추론	토큰 시퀀스를 보고 “tool을 쓸까 말까” 판단. 다음 토큰 예측의 반복	4편
Constrained Decoding	tool call의 인자가 항상 valid JSON이 되도록 생성을 제한	4편
출력 파싱	모델이 생성한 토큰에서 tool call 패턴을 감지하고 JSON으로 변환	4편

tool calling의 전체 라이프사이클

Anthropic 공식 문서에서 설명하는 tool use의 라이프사이클은 4단계다:

1. tool 정의와 사용자 프롬프트 제공 - tool의 이름, 설명, input schema를 JSON으로 정의하여 API에 전달
2. 모델이 tool 사용을 결정 - 모델이 사용자 쿼리에 도움이 되는 tool이 있는지 평가하고, 있으면 tool use 요청을 구성. 응답의 stop_reason이 tool_use로 설정된다
3. tool 실행 및 결과 반환 - 응답에서 tool 이름과 input을 추출하여 실제로 실행. 결과를 tool_result로 모델에 반환
4. 모델이 최종 응답 생성 - tool 결과를 분석하여 사용자에게 자연어 응답을 생성

sequenceDiagram
    autonumber
    participant App as 애플리케이션
    participant Claude as Claude API

    App->>Claude: tools 정의 + "서울 날씨 알려줘"
    Claude-->>App: stop_reason: "tool_use"<br/>name: "get_weather"<br/>input: { location: "Seoul" }
    Note over App: get_weather("Seoul") 실행
    App->>Claude: tool_result: "15°C, 맑음"
    Claude-->>App: "서울의 현재 날씨는 15°C이며 맑습니다"

핵심은 LLM이 tool을 직접 실행하지 않는다는 것이다. LLM은 “어떤 tool을, 어떤 인자로 호출해야 하는지”를 기술하는 데이터 구조를 만들 뿐이고, 실제 실행은 애플리케이션 코드에서 한다.

다음 편: API JSON이 모델에 어떻게 전달되는 거지?

이 글에서 5개 레이어의 존재를 확인했다. 그런데 첫 번째 레이어부터 의문이 든다.

우리가 API에 보내는 것은 JSON이다:

{
  "tools": [{ "name": "get_weather", "input_schema": { ... } }],
  "messages": [{ "role": "user", "content": "서울 날씨 알려줘" }]
}

하지만 LLM은 JSON 파서가 아니다. 이 JSON이 모델에 직접 들어가는 걸까?

아니다. 다음 편에서 이 JSON이 어떤 형태의 텍스트로 변환되어 모델에 전달되는지, 그리고 벤더마다 그 형태가 어떻게 다른지를 살펴본다.

참고 문서

• Anthropic - Tool Use Overview - Claude tool use 공식 문서, 라이프사이클 4단계 설명
• Martin Fowler - Function Calling using LLMs - LLM은 함수를 실행하지 않고 호출을 기술하는 데이터 구조를 생성한다는 핵심 개념
• MCP - Build an MCP Client - MCP tool을 Claude API 형식으로 변환하는 방법