Kimi Official Tools

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

Kimi Open Platform은 자유롭게 통합할 수 있는 공식 도구 세트를 제공합니다 (공식 도구는 현재 한정 기간 무료 — 도구 부하가 용량 한계에 도달하면 일시적 속도 제한이 적용될 수 있음). 이 문서는 사용 가능한 공식 도구 목록과 Kimi API를 통한 호출/실행 방법을 보여줍니다.

⚠️ 업데이트 안내: 웹 검색(web_search)은 현재 업데이트 중이라 가까운 시일 내 사용을 권장하지 않습니다. 후속 업데이트를 따라가 주세요.

1. 사용 가능한 공식 도구

도구명	설명
convert	단위 변환 — 길이, 질량, 부피, 온도, 넓이, 시간, 에너지, 압력, 속도, 통화 변환 지원
web-search	실시간 정보·인터넷 검색 도구. 가격·가용성은 Web Search Price 참고
rethink	지능형 추론 도구
random-choice	무작위 선택 도구
mew	무작위 고양이 울음과 축복 도구
memory	메모리 저장·조회 — 대화 기록·사용자 선호 영속 저장
excel	Excel·CSV 파일 분석 도구
date	날짜·시간 처리 도구
base64	Base64 인코딩·디코딩 도구
fetch	URL 콘텐츠 추출·Markdown 포맷팅 도구
quickjs	Quick JS 엔진 보안 JavaScript 코드 실행 도구
code-runner	Python 코드 실행 도구

2. Formula 개념 이해

공식 도구를 호출하기 전, Formula 개념을 이해해야 합니다. Formula는 Python 스크립트를 "AI가 원클릭으로 트리거할 수 있는 즉시 컴퓨팅 자원"으로 변환하는 경량 스크립트 엔진 모음입니다. 개발자는 코드 작성에만 집중하고, 플랫폼이 시작·스케줄링·격리·과금·재활용을 처리합니다.

Formula는 시맨틱 URI(예: moonshot/web-search:latest)로 호출. 각 Formula는 declaration(AI에게 무엇을 할 수 있는지 알림)과 implementation(Python 코드)를 포함하며, 플랫폼이 시작·격리·재활용 등 모든 기반을 자동 처리합니다. Playground에서 실험하거나 API로 호출 가능.

3. Formula 직접 호출 (curl 예시)

export FORMULA_URI="moonshot/web-search:latest"
export MOONSHOT_BASE_URL="https://api.moonshot.ai/v1"

curl -X POST ${MOONSHOT_BASE_URL}/formulas/${FORMULA_URI}/fibers \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $MOONSHOT_API_KEY" \
-d '{
  "name": "web_search",
  "arguments": "{\"query\": \"Moonshot AI 최신 뉴스를 검색해줘\"}"
}'

Formula URI는 보통 3 부분으로 구성 (예: moonshot/web-search:latest):

• web-search — name
• moonshot — namespace (현재 유일)
• latest — 기본 태그

web-search는 protected로 설정되어 있어 결과가 context.encrypted_output에 ----MOONSHOT ENCRYPTED BEGIN----...----MOONSHOT ENCRYPTED END---- 형식으로 표시됩니다. 이 콘텐츠는 도구 호출에 그대로 전달 가능.

4. Chat Completions와 통합

4-1. 도구 정의 가져오기

curl ${MOONSHOT_BASE_URL}/formulas/${FORMULA_URI}/tools \
    -H "Authorization: Bearer $MOONSHOT_API_KEY"

응답 예시:

{
  "object": "list",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "web_search",
        "description": "Search the web for information",
        "parameters": {
          "type": "object",
          "properties": {
            "query": {
              "description": "What to search for",
              "type": "string"
            }
          },
          "required": ["query"]
        }
      }
    }
  ]
}

tools 필드를 요청의 tools 리스트에 그대로 추가. 플랫폼이 API 호환을 보장합니다.

주의:

• type=function인 경우 단일 API 요청 내에서 function.name이 고유해야 함 — 중복 시 400 에러(function name ... is duplicated)로 즉시 거부됨
• 여러 Formula를 동시에 사용하는 경우, 추후 참조를 위해 function.name → formula_uri 매핑을 직접 유지

4-2. 모델의 도구 호출 처리

채팅 completion이 finish_reason=tool_calls을 반환하면 모델이 도구 호출을 트리거한 상태:

{
  "id": "chatcmpl-1234567890",
  "object": "chat.completion",
  "choices": [{
    "message": {
      "role": "assistant",
      "tool_calls": [{
        "id": "web_search:0",
        "type": "function",
        "function": {
          "name": "web_search",
          "arguments": "{\"query\": \"하늘색 RGB 값은?\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

choices[0].message.tool_calls[0].function.name에서 web_search 호출이 필요함을 알 수 있고, 매핑된 formula_uri는 moonshot/web-search:latest. choices[0].message.tool_calls[0].function을 그대로 body로 복사해 ${MOONSHOT_BASE_URL}/formulas/${FORMULA_URI}/fibers에 POST.

function.arguments는 이미 유효한 JSON이지만 문자열 형식 — escape 불필요, 그대로 body로 사용.

4-3. Fiber 결과 처리

Fiber는 특정 실행의 "프로세스 스냅샷"으로, 로그·Tracing·자원 사용량을 포함(디버깅/감사 용이). POST 결과의 status는 succeeded 또는 다양한 에러가 될 수 있음. 성공 시:

{
  "id": "fiber-f43p7sby7ny111houyq1",
  "object": "fiber",
  "status": "succeeded",
  "context": {
    "input": "{\"name\":\"web_search\",\"arguments\":...}",
    "encrypted_output": "----MOONSHOT ENCRYPTED BEGIN----+nf6...DSM=----MOONSHOT ENCRYPTED END----"
  },
  "formula": "moonshot/web-search:latest"
}

검색 도구는 encrypted_output을, 일반 도구는 output을 반환 — 이 출력이 다음 라운드의 입력. 메시지 배열은 다음과 같이 구성:

messages = [
  // 다른 메시지들
  { // 이전 라운드 모델 반환
    "role": "assistant",
    "tool_calls": [{
      "id": "web_search:0",
      "type": "function",
      "function": {
        "name": "web_search",
        "arguments": "{\"query\": \"하늘색 RGB 값은?\"}"
      }
    }]
  },
  { // 보충할 정보
    "role": "tool",
    "tool_call_id": "web_search:0",  // 이전 tool_calls[].id와 일치
    "content": "----MOONSHOT ENCRYPTED BEGIN----+nf6...DSM=----MOONSHOT ENCRYPTED END----"
  }
]

모델이 이후 추론을 이어갑니다.

5. 주의사항

• 모델이 여러 tool_calls를 반환할 수 있음 — 모든 tool_calls에 대한 결과를 반환해야 모델이 계속할 수 있음, 하나라도 누락 시 요청이 무효 처리됨
• assistant 메시지에 tool_calls가 있으면, 다음 메시지들은 정확히 같은 개수의 role=tool 메시지여야 하며, tool_call_id는 이전 tool_calls.id와 일대일 매칭:
  • 여러 tool_calls가 있을 때 순서는 중요하지 않음
  • 모델이 출력한 tool_calls의 id는 항상 고유, role=tool 메시지의 id도 그것들과 정렬 필수
  • 고유성 요구는 이번 라운드 tool_calls 응답 내에서만 — 전체 대화 또는 글로벌이 아님

---

변경 이력

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