Kimi 官方工具（Official Tools）是 Moonshot AI 免费提供的一组内置工具，包括联网搜索、单位换算、Excel 分析、随机选择、日期处理等，通过 Formula URI 动态加载，无需开发者实现工具逻辑。本文说明如何获取工具列表、注册和使用这些工具。

Kimi 官方工具（Official Tools）

可用工具一览

工具	Formula URI	说明
联网搜索	moonshot/web-search:latest	与 $web_search 类似，但通过官方工具协议调用
单位换算	moonshot/unit-converter:latest	长度、重量、温度等单位转换
Excel 分析	moonshot/excel-analyzer:latest	分析 Excel 文件内容
随机选择	moonshot/random-selector:latest	从列表中随机选取元素
日期处理	moonshot/date-handler:latest	日期计算和格式转换

与 $web_search 的区别：官方工具通过 Formula URI 动态加载，工具 schema 由 API 返回；$web_search 是硬编码的内置工具，不需要查询。两者功能类似但使用方式不同。

---

动态获取工具列表

import os
import json
import requests
from openai import OpenAI

api_key = os.environ.get("MOONSHOT_API_KEY")
base_url = "https://api.moonshot.cn/v1"

# 获取官方工具定义（动态加载）
tool_formula_uris = [
    "moonshot/web-search:latest",
    "moonshot/unit-converter:latest",
]

response = requests.get(
    f"{base_url}/tools",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"formula_uris": ",".join(tool_formula_uris)},
)
tools = response.json()["tools"]

# tools 是标准 OpenAI tools 格式，可直接用于 chat completions
print(json.dumps(tools, ensure_ascii=False, indent=2))

---

完整调用示例

client = OpenAI(api_key=api_key, base_url=base_url)

# 维护 formula_uri 到工具名的映射
formula_uri_map = {
    "moonshot/web-search:latest": "web_search",
    "moonshot/unit-converter:latest": "unit_converter",
}

messages = [
    {"role": "system", "content": "你是一个助手，可以使用工具回答问题。"},
    {"role": "user", "content": "1英里等于多少公里？"},
]

while True:
    response = client.chat.completions.create(
        model="kimi-k2.6",
        messages=messages,
        tools=tools,
    )
    choice = response.choices[0]

    if choice.finish_reason != "tool_calls":
        print(choice.message.content)
        break

    messages.append(choice.message)

    # 同一轮的所有 tool_calls 必须全部回复，不能只回复部分
    for tool_call in choice.message.tool_calls:
        tool_name = tool_call.function.name
        args = json.loads(tool_call.function.arguments)

        # 官方工具：调用 Kimi 工具 API 执行
        result = call_official_tool(tool_name, args, api_key, base_url)

        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result, ensure_ascii=False),
        })

def call_official_tool(tool_name: str, args: dict, api_key: str, base_url: str) -> dict:
    response = requests.post(
        f"{base_url}/tools/{tool_name}/call",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=args,
    )
    return response.json()

---

关键注意事项

1. 必须全量回复 tool_calls：同一轮中如果模型调用了 N 个工具，必须将所有 N 个工具的结果都添加到 messages，缺少任何一个都会导致下一次请求报错

2. 维护 formula_uri 映射：工具名称（tool_call.function.name）与 Formula URI 之间需要你自己维护映射关系，用于后续路由到正确的调用逻辑

3. tool_call_id 必须对应：回复 tool 消息时，tool_call_id 必须与 choice.message.tool_calls 中的 id 完全一致

---

常见问题

Q: 官方工具是否收费？

A: 官方工具本身免费集成，但工具调用过程中消耗的 token（工具输入/输出进入上下文）按正常 token 费率计费。联网搜索类工具还会额外计算搜索次数费用。

Q: 可以同时使用官方工具和自定义工具吗？

A: 可以，在 tools 数组中混合放置官方工具和自定义 function 工具即可。回调时通过 tool_call.function.name 区分是哪个工具。

Q: 如何知道有哪些最新的官方工具？

A: 调用 GET /v1/tools 接口并传入已知的 Formula URI，或直接访问 Kimi 开放平台控制台查看官方工具列表和更新日志。