Kimi Dynamic Tool Loading

상위 문서: ← Kimi Tooling workflows 출처: Kimi API Platform 공식 문서 — Dynamically Loaded Tools 한글화 (2026-07-22) 공급사: Moonshot AI (月之暗面)

애플리케이션이 수많은 도구를 필요로 할 때, 매 요청의 최상위 tools 필드에 모든 도구를 선언하면 Tool Definition Bloat 문제가 발생합니다 — 매 요청이 모든 도구의 설명과 파라미터 스키마를 담고 있어 토큰 사용량이 증가하고, 후보 도구가 많을수록 모델이 잘못된 도구를 고르거나 잘못된 인자를 생성할 가능성이 커집니다.

Dynamically Loaded Tools는 대화 중 필요할 때 도구를 주입해 이 문제를 해결합니다. 처음에는 핵심 도구 몇 개만 두고, 대화가 실제로 필요로 할 때 messages에 추가 도구를 삽입합니다. 토큰 사용량을 줄이면서 도구 선택 정확도를 동시에 높일 수 있습니다. 도구 선언은 항상 messages 끝에 추가되므로 기존 대화 prefix는 변경되지 않아 이미 구축한 prefix cache를 깨뜨리지 않으며, Context Caching과 결합해 비용과 지연 시간을 더 줄일 수 있습니다. 설계 배경(지연 로딩, 도구 레지스트리)과 결합 패턴은 Kimi K3 API Tool Calling Best Practices 참고.

1. messages에 도구 선언 주입

role을 system으로 설정한 메시지를 messages에 삽입하고, 그 메시지의 tools 필드를 통해 로드할 도구를 선언합니다. 선언 포맷은 최상위 tools 필드와 동일하며, 완전한 도구 정의(name, description, parameters)를 포함해야 합니다.

{
  "messages": [
    {
      "role": "system",
      "content": "You are Kimi, an AI assistant developed by Moonshot AI.\nYou are capable of a wide range of tasks..."
    },
    {
      "role": "user",
      "content": "Calculate fuel consumption."
    },
    {
      "role": "system",
      "tools": [
        {
          "type": "function",
          "function": {
            "name": "Calculator",
            "description": "A calculator that evaluates a single arithmetic expression",
            "parameters": {
              "type": "object",
              "properties": {
                "expr": {
                  "type": "string",
                  "description": "An arithmetic expression in JavaScript syntax; supports basic arithmetic, exponentiation, logarithms, and trigonometric functions"
                }
              },
              "required": ["expr"]
            }
          }
        }
      ]
    }
  ]
}

알아두기:

tools를 가진 system 메시지는 일반 입력 메시지와 동일한 위치를 가집니다 — 그 메시지가 messages 리스트에 나타나는 위치부터 도구가 모델에 노출됨
동적으로 로드한 도구는 최상위 tools 필드의 전역 도구와 공존하며, 모델은 양쪽 모두 볼 수 있음
동적 주입 도구 선언은 완전한 정의여야 함 — 도구 이름만 전달하거나 전역 선언을 참조하는 것은 불가능

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "system", "content": "You are Kimi, an AI assistant developed by Moonshot AI..."},
        {"role": "user", "content": "Help me compute 23 * 47."},
        # 동적 도구 로드: tools 필드를 가진 system 메시지 삽입
        {
            "role": "system",
            "tools": [
                {
                    "type": "function",
                    "function": {
                        "name": "Calculator",
                        "description": "A calculator that evaluates a single arithmetic expression",
                        "parameters": {
                            "type": "object",
                            "properties": {
                                "expr": {
                                    "type": "string",
                                    "description": "An arithmetic expression in JavaScript syntax...",
                                }
                            },
                            "required": ["expr"],
                        },
                    },
                }
            ],
        },
    ],
)

print(completion.choices[0].message.tool_calls)

2. 도구 검색(tool search) 구현

별도의 도구 검색 API는 없습니다. 도구 카탈로그가 크다면, 커스텀 검색 도구 + 동적 로드로 직접 구현할 수 있습니다.

최상위 tools 필드에 search_tools 함수 하나만 선언 (백엔드에서 구현) — 주어진 키워드에 매칭되는 도구 이름과 요약을 반환
시스템 프롬프트에 검색 가능한 키워드(도구 카탈로그, 도메인 태그 등)를 알려줘, 모델이 도구가 필요할 때 먼저 search_tools를 호출하도록 함
search_tools 반환 결과를 바탕으로, 매칭된 도구의 전체 선언을 tools 필드를 가진 system 메시지로 messages에 삽입
이후 생성에서 모델은 새로 로드된 도구를 호출

전체 도구 인벤토리가 아무리 커도, 각 요청은 소수의 도구 선언만 담게 되어 컨텍스트 윈도우와 모델의 선택 압력을 모두 통제 가능.

3. Context Caching에 미치는 영향

Dynamically loaded tools는 Context Caching과 결합할 수 있습니다. Context caching은 prefix 매칭으로 동작 — 현재 요청의 시작 부분이 이전 요청과 동일할 때만 cache hit이 가능하고, prefix 내 변경은 그 이후 cache를 무효화합니다. 도구 선언을 어떻게 주입하느냐가 cache hit률을 직접 결정합니다. 다음 원칙으로 cache hit률을 높이세요.

끝에만 추가, 중간 삽입 금지 — 새 도구 선언은 항상 messages 끝에 추가. 기존 prefix는 그대로 유지되어 이미 형성된 cache에 영향 없음. 중간에 메시지를 수정/삽입하면 그 지점 이후 cache 무효화
이미 주입한 선언은 유지 — 동적 도구 선언은 요청 단위 적용이며 서버는 보관하지 않음. 이전에 로드한 선언을 이후 요청에서도 변경 없이 유지하는 것을 권장 — 도구 가용성 유지 + 안정된 prefix로 cache hit 일관성. 단, 비즈니스 요구에 따라 조정 가능. 선언이 누락되면 그 도구는 다른 곳에서 선언되지 않는 한 호출 불가, 그리고 messages가 변경되었으므로 그 이후 prefix는 cache 미스
핵심 도구는 최상위에 고정 — 매 턴 필요한 도구는 최상위 tools에 고정 선언하고 변경하지 않음. 최상위 전역 도구 선언은 cache hit에 영향을 주지 않으므로 안정적으로 유지하면 prefix cache 효과 보존. 동적 주입은 on-demand 도구에만 사용

작업	Prefix cache 영향
`messages` 끝에 도구 선언 추가	기존 prefix cache 영향 없음
이전 주입 선언을 변경 없이 유지	Prefix 안정, cache hit 지속
중간 메시지 삭제/수정, 중간에 새 선언 삽입	변경 지점 이후 cache 무효화 가능
최상위 `tools` 필드에 전역 도구 선언	Cache hit 영향 없음

Caching 임계값: 새 요청이 prefix cache에 도달하려면 이전 요청의 prompt 토큰이 256을 초과해야 합니다. 256 미만이면 캐시되지 않고 폐기됩니다. 자세한 내용은 Context Caching 참고.

4. 주의사항

동적 도구 선언은 전역 tools 선언과 동일한 포맷 — 스키마 단일, 마이그레이션 비용 낮음
tools를 가진 system 메시지도 컨텍스트 길이를 소비 — 현재 대화에 실제로 필요한 도구만 주입
동적 로드 도구는 현재 kimi-k3에서만 지원. 다른 모델(예: kimi-k2.6)에서 사용 시 tokenization failed 에러 발생
tools를 가진 system 메시지는 content 필드를 함께 가질 수 없음 — 400 에러(cannot be used with content) 발생. OpenAI SDK 사용 시 extra_body 없이 messages에 직접 tools 필드 전달 가능

5. 관련 문서

Kimi K3 API Tool Calling Best Practices — 동적 로딩 + tool_choice + reasoning_effort 결합 패턴
Tool Choice — tool_choice로 모델의 도구 호출 동작 제어
Use Kimi API for Tool Calls — 전체 도구 호출 워크플로우와 예제
Model Parameter Reference — tool_choice 등 모델별 파라미터 지원

변경 이력

날짜	변경
2026-07-22	초판 작성 (공식 Dynamic Tool Loading 가이드 한글화)
2026-07-22	제목에 "Kimi" 접두사 추가, 본문 H1 중복 제거