Kimi Tooling workflows

공급사: Moonshot AI (月之暗面) | 공식 문서: platform.kimi.ai/docs 한글화 일자: 2026-07-22

대규모 도구 인벤토리, 공식 도구, 동적 로딩, 캐싱 등 Kimi API의 도구 호출 인프라(tooling workflows) 패턴을 정리한 가이드 모음입니다.

---

📚 도구 워크플로우 가이드

#	문서	설명
1	Kimi Dynamic Tool Loading	동적 도구 로딩 — 대규모 도구 인벤토리에서 필요한 도구만 컨텍스트에 주입
2	Kimi Tool Choice	tool_choice로 모델의 도구 호출 동작 제어 (force / forbid / auto / specific)
3	Kimi Tool Calling Best Practices	모범 사례 — 검색 도구 + tool_choice + reasoning_effort 결합 패턴
4	Kimi Official Tools	공식 도구 (Formula) — web-search, convert, memory 등 즉시 사용 가능
5	Kimi Web Search	내장 $web_search로 즉시 웹 검색
6	Kimi Context Caching	컨텍스트 캐싱 — 반복되는 초기 컨텍스트 자동 재사용

---

🎯 패턴 선택 가이드

시나리오	권장 패턴
도구 수십~수백 개 (에이전트 시스템)	Kimi Dynamic Tool Loading + Tool Calling Best Practices
도구 호출을 강제/금지하고 싶음	Kimi Tool Choice
검색·DB·외부 API를 손쉽게 붙이고 싶음	Kimi Official Tools (Formula)
최신 정보가 필요한 질문	Kimi Web Search (내장 $web_search)
큰 시스템 프롬프트/문서가 매 요청 반복	Kimi Context Caching

---

⚡ 빠른 시작: tool_choice로 강제 호출

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": "user", "content": "오늘 서울 날씨 알려줘"}}],
    tools=[{{
        "type": "function",
        "function": {{
            "name": "get_weather",
            "description": "특정 도시의 현재 날씨 조회",
            "parameters": {{
                "type": "object",
                "properties": {{"city": {{"type": "string", "description": "도시명"}}}},
                "required": ["city"],
            }},
        }},
    }}],
    tool_choice="required",  # 도구 호출 강제
)
print(completion.choices[0].message.tool_calls)

자세한 패턴은 각 가이드를 참고하세요.

---

📚 Tooling과 Capabilities의 경계

영역	페이지
Capabilities (#867)	도구 호출이 무엇을 할 수 있는지 (Vision, Tool Calls 기본, JSON Mode, Thinking, Streaming, Multi-turn)
Tooling workflows (#868, 이 페이지)	도구 호출 인프라 (대규모 인벤토리, 동적 로딩, 공식 도구, 캐싱, 검색)

---

📞 추가 리소스

리소스	링크
공식 API 문서	https://platform.kimi.ai/docs
Playground	https://platform.kimi.ai/playground
API Key 발급	https://platform.kimi.ai/console/api-keys
개발자 커뮤니티	https://platform.kimi.ai/docs/api/join-the-community

---

변경 이력

날짜	변경
2026-07-22	Tooling workflows를 hub 페이지로 전환, 6개 자식 가이드 한글화 (Dynamic Tool Loading / Tool Choice / Tool Calling Best Practices / Official Tools / Web Search / Context Caching)