LLM Tool Calling - Native vs Non-native

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

---

• Native vs Non-native는 2~5편에서 다룬 tool calling 레이어(Chat Template, Tokenization, 모델 추론, Constrained Decoding, 출력 파싱, Tool 실행 루프)가 모델/API에 내장되어 있는지 여부에 따른 구조적 차이
• Claude, GPT 같은 상용 모델은 이 레이어가 API 서버에 모두 내장되어 있지만, 오픈소스 모델(Llama, Gemma 등)은 모델 가중치만 존재하고 나머지 레이어가 없는 구조
• 이 격차를 외부에서 메우는 것이 Middleware이며, harness 설계가 모델 성능에 결정적 영향을 미친다는 것이 최근 연구의 핵심 발견

해당 개념이 필요한 이유

• 5편까지 tool calling 파이프라인의 모든 레이어를 확인했다. 하지만 이 레이어들이 항상 존재하는 것은 아니다
• 오픈소스 모델을 로컬에서 실행할 때 “tool calling이 안 된다”는 것이 구체적으로 어떤 레이어가 없다는 뜻인지 이해해야, 7편에서 middleware를 만들 수 있다
• 또한, harness(tool 포맷) 설계만 바꿔도 모델 성능이 10배 달라질 수 있다는 사실은 개발자에게 실질적 가치가 있다

AS-IS

sequenceDiagram
    autonumber
    box 개발자 영역
        participant Dev as 개발자
    end
    box AI 서비스 영역
        participant API as API 서버
        participant CT as Chat Template
        participant TK as Tokenizer
        participant LLM as 모델
        participant CD as Constrained Decoding
        participant P as 출력 파서
    end

    Dev->>API: tools + 질문
    API->>CT: JSON → 텍스트
    CT->>TK: 텍스트 → 토큰
    TK->>LLM: 추론
    LLM->>CD: valid JSON 강제
    CD->>P: 파싱
    P->>API: structured JSON
    API-->>Dev: tool_use 응답
    Note over API,P: 모든 레이어가 내장되어 있다

TO-BE

sequenceDiagram
    autonumber
    box 개발자 영역
        participant Dev as 개발자
    end
    box ???
        participant Q as 누가 처리하지?
    end
    box 오픈소스 모델
        participant LLM as 모델 가중치만 존재
    end

    Dev->>Q: tools + 질문
    Note over Q: Chat Template?<br/>Tokenizer?<br/>Constrained Decoding?<br/>출력 파싱?
    Q->>LLM: ???
    LLM-->>Q: ???
    Q-->>Dev: ???

Native Tool Calling 모델의 구조

Claude, GPT 같은 상용 모델을 사용할 때, 개발자는 API에 JSON을 보내면 된다. 나머지는 모두 API 서버가 처리한다:

flowchart LR
    subgraph API서버["API 서버 (입력 처리)"]
        CT[Chat Template]
        TK[Tokenizer]
    end
    subgraph 모델
        LLM["모델 추론<br/>(tool call fine-tuning 완료)"]
    end
    subgraph API서버2["API 서버 (출력 처리)"]
        CD[Constrained Decoding]
        P[출력 파서]
    end

    CT --> TK --> LLM --> CD --> P

각 레이어의 역할 (2~5편 요약):

• Chat Template: tool JSON → 시스템 프롬프트 텍스트 변환
• Tokenizer: 텍스트 → 토큰 ID + control token 처리
• 모델 추론: fine-tuning으로 학습된 tool call 패턴 기반 판단
• Constrained Decoding: JSON schema에 맞는 토큰만 허용
• 출력 파서: 생성된 토큰 → structured JSON 변환

Non-native 모델에 없는 것

오픈소스 모델(Llama, Gemma, Mistral 로컬 등)을 HuggingFace에서 다운로드하면, 받는 것은 모델 가중치 파일이다. 위 레이어들은 포함되어 있지 않다:

레이어	Native (Claude, GPT)	Non-native (Llama 로컬)
Chat Template	API 서버에 내장	없음. 개발자가 직접 프롬프트 조립
Control Token	vocabulary에 포함	모델에 따라 다름. 없을 수 있음
Tool call fine-tuning	완료됨	없거나 불완전. 범용 모델은 tool call 패턴 미학습
Constrained Decoding	API 서버에 내장	없음. 모델이 아무 토큰이나 생성 가능
출력 파서	API 서버에 내장	없음. 모델 출력에서 tool call을 직접 추출해야 함
Tool 실행 루프	SDK에 내장 (toolRunner 등)	없음. 직접 구현

핵심: Non-native 모델에서 tool calling을 하려면, 이 모든 레이어를 외부에서 구현해야 한다. 이것을 담당하는 것이 Middleware다.

Middleware - 없는 레이어를 외부에서 메운다

sequenceDiagram
    autonumber
    box 개발자 영역
        participant Dev as 개발자
    end
    box Middleware (외부 구현)
        participant CT as 프롬프트 조립
        participant P as 출력 파싱
    end
    box 오픈소스 모델
        participant LLM as 모델 가중치
    end

    Dev->>CT: tools 정의 + "서울 날씨 알려줘"
    CT->>LLM: tool 정의를 포함한 텍스트 프롬프트
    LLM-->>P: 텍스트 출력 (XML 등 패턴 포함)
    P->>P: tool call 패턴 감지 및 JSON 추출
    P-->>Dev: tool_use: get_weather("Seoul")
    Note over Dev: tool 실행 후 결과 반환
    Dev->>CT: tool_result: "15°C, 맑음"
    CT->>LLM: 결과 포함 프롬프트
    LLM-->>P: 최종 텍스트 응답
    P-->>Dev: "서울의 현재 날씨는 15°C입니다"

Middleware가 담당하는 3가지 역할:

1. 프롬프트 조립: tool 정의를 모델이 이해할 수 있는 텍스트로 변환 (Chat Template 대체)
2. 출력 파싱: 모델이 생성한 텍스트에서 tool call 패턴을 감지하고 JSON으로 추출
3. 실행 루프: tool 실행 → 결과를 모델에 피드백 → 추가 tool call 확인 → 반복

실제 구현체: ai-sdk-tool-call-middleware

Vercel AI SDK의 middleware 구조를 활용하면, native tool calling을 지원하지 않는 모델에도 tool calling을 붙일 수 있다:

import { wrapLanguageModel } from "ai";
import { toolCallMiddleware } from "@ai-sdk-tool/parser";
 
// 오픈소스 모델을 middleware로 감싸기
const wrappedModel = wrapLanguageModel({
  model: ollamaModel,  // tool calling 미지원 모델
  middleware: toolCallMiddleware({
    protocol: "xml",  // XML 형식으로 tool call 인코딩
  }),
});
 
// 이제 native tool calling처럼 사용 가능
const result = await generateText({
  model: wrappedModel,
  tools: { /* tool 정의 */ },
  prompt: "서울 날씨 알려줘",
});

middleware가 내부적으로 하는 일:

1. tools JSON을 XML 형식의 시스템 프롬프트로 변환 (Chat Template 대체)
2. 모델 출력에서 <tool_call> 패턴을 감지하여 파싱 (출력 파서 대체)
3. 파싱된 결과를 AI SDK의 tool_use 형식으로 변환

보안: control token이 없다는 것의 의미

3편에서 Native 모델은 control token으로 tool 정의 영역을 보호한다고 설명했다. Middleware 방식에서는 control token이 없다. tool 정의가 일반 텍스트로 프롬프트에 삽입되므로, 이론적으로 사용자가 프롬프트에 <tool_call> 같은 패턴을 삽입하여 injection할 위험이 Native보다 높다.

다만 완전히 무방비는 아니다. middleware는 출력 측에서 정해진 XML 패턴만 감지하고, 입력의 사용자 메시지 영역과 시스템 프롬프트 영역을 분리하여 처리한다. 하지만 Native 모델의 control token 수준의 보안은 제공하지 못한다는 한계가 있다.

보안이 특히 중요한 B2B 환경이라면, 오픈소스 모델을 온프레미스로 배포하는 방법이 있다. 데이터가 외부 벤더 서버로 전송되지 않으므로, injection 위험과 별개로 데이터 유출 자체를 원천 차단할 수 있다.

Vercel AI SDK의 middleware도 이 구성에서 사용 가능하다. middleware는 npm 패키지(클라이언트 라이브러리)일 뿐이므로, 어디서 실행되느냐는 개발자가 결정한다. 고객사 서버에서 실행하면 데이터가 Vercel 서버로 전송되지 않는다.

각 구성요소의 실행 위치

혼동하기 쉬운 점: “Vercel AI SDK”라는 이름 때문에 Vercel 클라우드를 경유한다고 오해할 수 있다. 하지만 SDK도, middleware도, vLLM도 모두 자체 서버에서 실행되는 소프트웨어다.

구성요소	정체	설치 방법	데이터가 외부로 나가는가
vLLM	로컬 서빙 프레임워크	pip install vllm → 자체 서버에서 실행	나가지 않음. localhost에서 API 제공
Vercel AI SDK	npm 패키지 (클라이언트 라이브러리)	npm install ai → 자체 코드에서 import	나가지 않음. Vercel 클라우드와 무관
@ai-sdk-tool/parser	npm 패키지 (middleware)	npm install @ai-sdk-tool/parser	나가지 않음. 로컬에서 프롬프트 변환/파싱

데이터가 외부로 나가느냐는 SDK 자체가 아니라, SDK에 어떤 모델을 연결하느냐에 따라 결정된다:

anthropic("claude-opus-4-6")                                   → Anthropic 서버로 요청 (외부 나감)
ollama("qwen3:8b")                                             → localhost Ollama로 요청 (외부 안 나감)
createOpenAICompatible({ baseURL: "http://내서버:8000/v1" })     → 자체 vLLM으로 요청 (외부 안 나감)

온프레미스 구성 예시

자체 서버 (내부망)
├── vLLM (모델 서빙)             ← pip install, localhost:8000
├── Vercel AI SDK (npm 패키지)   ← npm install, 같은 서버에서 실행
├── @ai-sdk-tool/parser (npm)   ← npm install, 같은 서버에서 실행
└── 애플리케이션 코드              ← tool 정의 + 실행 함수

모든 데이터가 고객사 내부망에서 처리, 외부 통신 없음.

Harness 설계가 성능을 결정한다

AI harness는 “모델을 ‘말하는 뇌’에서 ‘일하는 시스템’으로 만드는 전체 실행 프레임(스캐폴딩)“이다. Orchestration, Memory, Tools, Verification, Artifacts를 모두 포함한다 (Anthropic, The Harness Problem 모두 동일한 넓은 의미로 정의).

The Harness Problem 블로그는 이 harness의 구성요소 중 Tools 레이어의 형식 설계를 실험으로 검증했다. “코드 편집”이라는 과제에서, tool이 수정 사항을 어떤 형식으로 표현하느냐에 따라 성능이 극적으로 달라진다는 것을 보여준다.

harness (전체 실행 프레임)
├── Orchestration (계획 → 실행 → 관찰 루프)
├── Memory (상태 보존, 세션 브리징)
├── Tools ← The Harness Problem이 실험한 영역
│   └── 코드 편집 tool의 형식
│       ├── patch
│       ├── str_replace
│       └── hashline
├── Verification (테스트, 검증)
└── Artifacts (로그, git history)

16개 모델을 대상으로 코드 편집 tool의 3가지 형식을 비교한 결과:

tool 형식	동작 방식	대표적 문제
patch	diff 형식으로 수정 표현 (- 삭제, + 추가)	Grok 4: 50.7% 실패. diff 문법 생성 자체에서 오류 발생
str_replace	원본 텍스트를 정확히 매칭하여 교체	공백/들여쓰기 불일치로 “String to replace not found” 빈번
hashline	라인별 content hash로 위치를 참조	대부분의 모델에서 str_replace와 동등하거나 우세

핵심 인사이트:

“모델이 과제를 이해하지 못하는 것이 아니다. harness(의 tool 형식 설계)에서 실패하는 것이다.”

Grok Code Fast 모델의 경우, tool 형식만 변경하여 6.7% → 68.3% (10배 향상)를 달성했다. 이것은 모델 자체를 업그레이드한 것이 아니라, harness의 tool 형식 설계만 바꾼 결과다.

hashline의 동작 방식

hashline은 위 표에서 보듯 patch, str_replace와 같은 레벨의 코드 편집 tool 형식 중 하나다. 파일을 읽을 때 각 라인에 content hash를 부여:

1:a3|function hello() {
2:f1|  return "world";
3:0e|}

모델은 정확한 텍스트를 재현할 필요 없이, hash로 라인을 참조:

• “라인 2:f1을 교체해줘”
• “라인 1:a3부터 3:0e까지 범위를 교체해줘”
• hash가 불일치하면 파일이 변경된 것이므로 자동으로 감지

vLLM - 서빙 프레임워크의 역할

오픈소스 모델을 다운로드하면 모델 가중치만 존재한다. 이것을 OpenAI API 호환 HTTP 서버로 감싸서, Claude/GPT API처럼 사용할 수 있게 해주는 것이 vLLM 같은 서빙 프레임워크다.

vLLM이 제공하는 것:

• tool parser: 모델별 tool call 출력 형식을 감지하여 OpenAI API 호환 형태로 변환 (Hermes, Mistral, Llama 등 전용 파서)
• guided decoding: constrained decoding을 서빙 레벨에서 지원 (4편에서 다룬 JSON schema 강제)
• chat template: 모델의 tokenizer_config.json에서 chat template을 자동 로드 (2편에서 다룬 변환 자동화)

다음 편: 그러면 직접 만들어보자

이 글에서 Native 모델과 Non-native 모델의 구조적 차이를 확인했다. Non-native 모델에는 5개 레이어 중 대부분이 없고, 이를 외부에서 메우는 것이 Middleware다.

다음 편에서는 이 Middleware를 직접 만들어본다. 프롬프트 조립, 출력 파싱, 실행 루프의 3가지 역할을 코드로 구현한다.

참고 문서

• ai-sdk-tool-call-middleware - 실제 middleware 구현체 (Vercel AI SDK 기반)
• ai-sdk-tool-call-middleware PR #178 - XML protocol 개선
• The Harness Problem - harness 설계가 성능에 미치는 영향, hashline 소개. Grok Code Fast 6.7% → 68.3%
• Vercel AI SDK - Language Model Middleware - wrapLanguageModel, middleware 구조
• vLLM - Tool Calling - 서빙 프레임워크의 tool parser, guided decoding
• @ai-sdk-tool/parser npm - XML/Hermes 프로토콜 기반 tool call parser middleware