Kimi Tool Calling Best Practices

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

에이전트가 대규모 도구 인벤토리를 가질 때, 동적 로딩 + tool_choice + reasoning_effort를 도구 호출 흐름에서 결합하세요.

에이전트가 수십~수백 개의 도구에 접근할 때, 모든 도구 정의를 요청에 넣지 마세요 — 컨텍스트를 잡아먹고 모델이 잘못된 도구를 고를 가능성이 커집니다. 이 가이드는 Kimi K3에서 도구 오케스트레이션 설정을 다룹니다: 검색 도구로 후보 도구를 먼저 찾고, 대화 중 필요할 때 도구 정의를 주입하세요.

1. 모든 도구가 아닌 검색 도구만 선언

대화 시작 시 search_tools 함수 하나 + 매 턴 사용할 것으로 예상되는 핵심 소수 도구만 선언:

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_tools",
        "description": "Search available tools by keyword and return matching tool names and summaries",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Search keyword, e.g. github or database"
            }
          },
          "required": ["query"]
        }
      }
    }
  ]
}

시스템 프롬프트에 모델이 검색할 수 있는 도메인 태그(도구 카탈로그, 비즈니스 도메인 등)를 알려, 도구가 필요할 때 먼저 search_tools를 호출하도록 합니다. 전체 인벤토리가 아무리 커도, 각 요청은 소수의 도구 선언만 담게 됨.

2. `tool_choice`로 첫 턴 검색 강제

모델이 도구를 호출하지 않고 메모리에서 답변할 수 있습니다. 답변 전 검색을 보장하려면 첫 턴에 tool_choice: "required" 설정:

{
  "model": "kimi-k3",
  "messages": [{"role": "user", "content": "Help me create a GitHub PR"}],
  "tools": ["..."],
  "tool_choice": "required"
}

검색 후 후속 요청에서 tool_choice를 "auto"로 복귀. tool_choice 변경은 prefix cache를 무효화하지 않으므로 요청별로 자유 조정 가능. 모든 허용 값은 Tool Choice 참고.

3. 필요할 때 도구 정의 주입

search_tools가 후보 도구를 반환하면, 애플리케이션은 매칭된 도구의 전체 선언을 tools 필드를 가진 system 메시지로 messages에 삽입. 도구는 그 메시지 위치부터 모델에 노출됩니다:

{
  "role": "system",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "create_github_pr",
        "description": "Create a pull request in the given repository",
        "parameters": {
          "type": "object",
          "properties": {}
        }
      }
    }
  ]
}

동적 선언은 최상위 tools 필드와 정확히 같은 포맷 — 두 번째 스키마 불필요, 전역 선언과 공존. 동적 도구 선언은 요청 단위 적용이며 서버는 보관하지 않음. 다음 요청에서 클라이언트는 원래 선언을 그대로 유지해 도구 가용성 유지 + prefix cache 재사용, 또는 제거 가능. 다른 곳에서 선언되지 않으면 모델은 그 도구를 호출할 수 없으며, prefix가 변경되어 cache 미스 가능. 자세한 사용법은 Dynamically Loaded Tools 참고.

Caching 임계값: 새 요청이 prefix cache에 도달하려면 이전 요청의 prompt 토큰이 256을 초과해야 함. 자세한 내용은 Context Caching 참고.

4. 작업에 맞는 reasoning effort 선택

최상위 reasoning_effort 요청 필드는 low, high, max를 지원하며 기본값은 max입니다.

대화가 시작되기 전에 이 설정을 결정하세요. messages 끝에 동적 도구 선언을 추가하는 것은 cached prefix에 영향을 주지 않음. 그러나 이전 도구 선언을 삭제/수정하면 변경 지점 이후 cache hit에 영향. tool_choice 변경은 prefix cache를 무효화하지 않음. 설정 상세는 Reasoning Effort 참고.

5. 전체 흐름

대화 시작 — 최상위 tools에 search_tools + 소수 핵심 도구만
첫 턴 검색 — tool_choice: "required"로 search_tools 강제 호출
필요 시 주입 — 검색 결과를 바탕으로 system 메시지로 도구 정의 주입
직접 호출 — 후속 생성에서 모델이 로드된 도구 호출
Reasoning effort — 대화 시작 전에 최상위 reasoning_effort 결정

6. 관련 문서

변경 이력

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