LLM Tool Calling - Chat Template

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

---

• Chat Template은 API가 받은 tools JSON과 messages를 모델이 이해할 수 있는 하나의 긴 프롬프트 텍스트로 조립하는 변환 레이어
• LLM은 JSON을 직접 파싱하지 않으며, 모든 입력은 텍스트 문자열로 변환되어 모델에 전달되는 구조적 전처리 과정
• 벤더마다 변환 형태가 다르며(Claude는 시스템 프롬프트, OpenAI는 비공개 템플릿, Gemini는 function_declarations, Mistral은 control token, GLM은 XML 태그), 이것이 모델이 실제로 보는 입력의 실체

해당 개념이 필요한 이유

• 1편에서 5개 레이어 중 첫 번째가 Chat Template이라는 것을 확인했다. 하지만 “JSON이 텍스트로 변환된다”는 것이 구체적으로 어떤 의미인지는 아직 블랙박스다
• tool 정의를 잘 작성하려면, 그것이 모델에게 어떤 형태로 보이는지 알아야 한다. description이 길면 토큰을 많이 소비하는 이유도 여기에 있다
• 벤더마다 변환 형태가 다르다는 것은, 같은 tool 정의도 모델에 따라 다르게 해석될 수 있다는 뜻이다

AS-IS

sequenceDiagram
    autonumber
    box 개발자 영역
        participant Dev as 개발자
    end
    box AI 서비스 영역
        participant API as API 서버
        participant LLM as LLM
    end

    Dev->>API: tools JSON + messages JSON
    Note over API,LLM: JSON이 그대로 모델에 들어간다?
    LLM-->>API: tool_use 응답

TO-BE

sequenceDiagram
    autonumber
    box 개발자 영역
        participant Dev as 개발자
    end
    box AI 서비스 영역
        participant API as API 서버
        participant CT as Chat Template
        participant LLM as LLM
    end

    Dev->>API: tools JSON + messages JSON
    API->>CT: JSON 분해
    CT->>LLM: 하나의 긴 프롬프트 텍스트
    Note over CT,LLM: "In this environment you have access to..."
    LLM-->>API: tool_use 응답

API JSON은 모델에 직접 들어가지 않는다

개발자가 API에 보내는 것은 structured JSON이다:

const response = await anthropic.messages.create({
  model: "claude-opus-4-6",
  tools: [{
    name: "get_weather",
    description: "Get the current weather in a given location",
    input_schema: {
      type: "object",
      properties: {
        location: { type: "string", description: "The city and state" }
      },
      required: ["location"]
    }
  }],
  messages: [{ role: "user", content: "서울 날씨 알려줘" }]
});

하지만 LLM은 JSON 파서가 아니다. 이 JSON은 API 서버에서 Chat Template을 통해 하나의 텍스트 문자열로 변환된 후 모델에 전달된다.

Claude의 Chat Template - 시스템 프롬프트 삽입

Anthropic은 공식 문서에서 이 변환 결과를 공개하고 있다. tools 파라미터를 사용하면 API가 자동으로 다음과 같은 시스템 프롬프트를 구성한다:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format.
Note that spaces for string values are not stripped.
The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

즉, 개발자가 보낸 tools JSON 배열이 {{ TOOL DEFINITIONS IN JSON SCHEMA }} 자리에 텍스트로 삽입된다. 모델 입장에서는 이것이 그냥 시스템 프롬프트의 일부 텍스트일 뿐이다.

이것이 의미하는 것:

• tool의 description이 길수록 시스템 프롬프트가 길어지고, 입력 토큰이 증가한다
• Anthropic 공식 문서에 따르면 tool use 시 모델별로 313~530개의 추가 시스템 프롬프트 토큰이 소비된다 (tool 정의 토큰 제외)
• “모델이 tool을 이해한다”는 것은 마법이 아니라, 시스템 프롬프트에 적힌 지시를 따르는 것이다

OpenAI(GPT)의 Chat Template - 비공개 시스템 프롬프트

OpenAI는 Claude와 동일하게 tool 정의를 시스템 메시지에 삽입하지만, 정확한 내부 포맷은 공개하지 않는다.

공식적으로 확인된 것:

• tool 정의(description, param types 등)가 프롬프트의 일부로 모델에 전달된다
• 특수 토큰으로 tool 정의의 시작과 끝을 구분하는 것으로 추정되지만, 정확한 토큰은 비공개
• tool 정의는 입력 토큰으로 계산되어 과금된다

GPT-4.1 공식 가이드에서는 tool 스키마를 시스템 프롬프트에 직접 삽입하는 대신 API의 tools 필드를 사용할 것을 권장한다. API를 통해 전달하면 모델이 학습된 내부 포맷에 맞게 변환되기 때문에, 수동 삽입 대비 SWE-bench에서 2% 높은 성능을 보였다.

Gemini(Google)의 Chat Template - function_declarations

Gemini는 OpenAPI 스키마 호환 형식으로 tool을 정의한다:

const response = await ai.models.generateContent({
  model: "gemini-3-flash",
  contents: "서울 날씨 알려줘",
  config: {
    tools: [{
      functionDeclarations: [{
        name: "get_weather",
        description: "Get current weather by city name",
        parameters: {
          type: "object",
          properties: {
            city: { type: "string", description: "City name" }
          },
          required: ["city"]
        }
      }]
    }]
  }
});

Gemini도 내부 변환 포맷을 공개하지 않지만, Gemini 2.5/3 시리즈는 내부 “thinking” 과정을 통해 어떤 함수를 호출할지, 어떤 파라미터를 사용할지 판단한다.

Mistral의 Chat Template - Control Token

Mistral(프랑스 AI 기업, 대표 모델: Mistral Large, Mixtral, Codestral)은 내부 포맷을 가장 상세하게 공개한 벤더다. 텍스트가 아닌 control token으로 tool 정의 영역을 감싼다:

<s>[AVAILABLE_TOOLS] [{"type": "function", "function": {"name": "calculator",
"description": "Performs mathematical calculations", "parameters": {"type":
"object", "properties": {"operation": {"type": "string"}},
"required": ["operation"]}}}] [/AVAILABLE_TOOLS]
[INST] What's 2+2? [/INST]
[TOOL_CALLS] [{"name": "calculator", "arguments": {"operation": "2+2"}}]</s>
[TOOL_RESULTS] [{"name": "calculator", "content": 4}] [/TOOL_RESULTS]
2+2=4</s>

여기서 [AVAILABLE_TOOLS], [TOOL_CALLS], [TOOL_RESULTS]는 일반 텍스트가 아니라 control token이다. 이 차이는 3편(Tokenization)에서 자세히 다룬다.

핵심은 동일하다: JSON이 그대로 모델에 들어가는 것이 아니라, 특정 형태의 텍스트 시퀀스로 변환된다.

GLM의 Chat Template - 특수 토큰 + XML 태그

GLM(중국 칭화대 THUDM 팀, 대표 모델: GLM-4, ChatGLM, GLM-4.6)은 특수 토큰으로 역할을 구분하고, XML 태그로 tool을 정의한다:

[gMASK]<sop><|system|>
# Tools
You may call one or more functions to assist with the user query.
You are provided with function signatures within <tools></tools> XML tags:
<tools>
{"type": "function", "function": {"name": "get_weather",
"description": "Get current weather by city name",
"parameters": {"type": "object", "properties":
{"city": {"type": "string"}}, "required": ["city"]}}}
</tools>
For each function call, output the function name and arguments within
the following XML format:
<tool_call>{function_name}<arg_key>{key}</arg_key>
<arg_value>{value}</arg_value></tool_call>
<|user|>
서울 날씨 알려줘
<|assistant|>
<think>

여기서:

• [gMASK]<sop> - 모델의 시작 특수 토큰
• <|system|>, <|user|>, <|assistant|> - 역할 구분 특수 토큰
• <tools>...</tools> - tool 정의 영역
• <tool_call>...<arg_key>...<arg_value>...</tool_call> - tool 호출 출력 형식
• <think> - 모델의 사고 과정 시작

벤더별 비교

세 벤더 모두 “JSON → 텍스트 변환”이라는 동일한 목적을 수행하지만, 방식이 다르다:

	Claude	OpenAI (GPT)	Gemini	Mistral	GLM
tool 정의 위치	시스템 프롬프트 텍스트	시스템 메시지 삽입 (비공개)	비공개	[AVAILABLE_TOOLS] control token	<tools> XML 태그
역할 구분	API 레벨에서 처리	API 레벨에서 처리	API 레벨에서 처리	[INST] 태그	<|system|> <|user|> 특수 토큰
tool call 출력	JSON (정규식 파싱)	JSON (비공개 파싱)	JSON (functionCall)	[TOOL_CALLS] + JSON	<tool_call> XML 태그
경계 표시	텍스트 지시문	특수 토큰 (추정)	비공개	control token (injection 불가)	특수 토큰 + XML
내부 포맷 공개	템플릿 구조 공개	비공개	비공개	토큰 수준 공개	모델 코드에서 확인 가능

핵심: 결국 모든 것은 텍스트

세 벤더의 방식이 달라 보이지만, 공통점은 하나다:

API JSON → 하나의 긴 텍스트 시퀀스 → 모델에 입력

모델은 이 텍스트를 읽고:

1. “어떤 tool이 사용 가능한지” 파악하고
2. “사용자가 무엇을 원하는지” 이해하고
3. “어떤 tool을 어떤 인자로 호출할지” 결정한다

이 결정이 마법처럼 보이지만, 실제로는 시스템 프롬프트에 적힌 지시를 따르는 것 + fine-tuning으로 학습된 패턴의 조합이다.

다음 편: 이 텍스트가 모델에 바로 들어가는 것도 아니다

Chat Template이 JSON을 텍스트로 변환한다는 것을 확인했다. 그런데 모델은 텍스트도 직접 처리할 수 없다.

모델은 수학 연산(행렬 곱셈)으로 동작하므로, 텍스트를 **숫자(토큰 ID)**로 변환하는 과정이 반드시 필요하다. 그리고 이 과정에서 Mistral의 [AVAILABLE_TOOLS] 같은 control token이 일반 텍스트와 어떻게 다르게 처리되는지가 드러난다.

다음 편에서 이 Tokenization 과정을 살펴본다.

참고 문서

• Anthropic - Tool Use System Prompt Structure - Claude가 공개한 실제 시스템 프롬프트 템플릿 (“In this environment you have access to…“)
• OpenAI - Function Calling Guide - GPT의 tool calling 공식 가이드
• OpenAI Community - Function Calling Prompt Injection - “tool 정의가 시스템 메시지에 삽입된다”는 공식 확인
• Gemini - Function Calling - Gemini의 function_declarations 형식과 워크플로우
• Mistral - Tokenization & Tool Calling Deep Dive - control token 기반 tool calling 형태 (가장 상세한 내부 포맷 공개)
• GLM-4 Chat Template - GLM-4의 특수 토큰과 chat template 구조
• GLM-4.6 Tool-Integrated Reasoning Guide - <tool_call>, <arg_key>, <arg_value> XML 형식
• HuggingFace - Chat Templates - chat template 일반 개념