Kimi K3.1 Pro 动态工具加载工作流：按需注入工具并保留缓存前缀

一句话结论

Kimi K3.1 Pro 可在对话需要时，通过追加 role="system" 且带 tools 的消息注入完整工具定义；按原样保留已加载定义，能减少工具定义 token，并维持已有前缀缓存。

适用场景

• 适合的任务：工具数量较多、需要按关键词搜索工具，再执行多步 Agent 调用的 API 工作流。

• 不适合的任务：工具集合固定且很小，或需要把工具名引用当作完整定义的请求。

• 适用的模型版本：kimi-k3.1-pro；文档同时明确支持 kimi-k3。

• 适用的客户端、Agent 或 API：Kimi API Chat Completions，以及能按消息追加完整工具定义的客户端或后端。

• 推荐的推理档位和参数：文档未为动态加载另设推理档位；固定工具放顶层 tools，按需工具放消息的 tools 字段。

可直接使用的内容

下面保留官方示例的最小结构。动态工具消息不能同时有 content：

{
  "model": "kimi-k3.1-pro",
  "messages": [
    {"role": "user", "content": "Help me compute 23 * 47."},
    {
      "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"]
          }
        }
      }]
    }
  ]
}

测试或工作流步骤

1. 把每轮都需要的核心工具放在顶层 tools，并保持定义不变。

2. 首轮只发送核心工具和当前对话，避免预先声明整个工具目录。

3. 应用自行实现 search_tools，返回匹配工具的名称与摘要；文档没有专用的工具搜索 API。

4. 根据搜索结果，在 messages 末尾追加一个 role="system" 消息，并在其 tools 字段放入完整定义。

5. 工具从该消息在 messages 中出现的位置开始对模型可见；顶层工具与动态工具同时可见。

6. 继续生成，让模型在后续生成中调用新加载的工具；工具实际执行、权限和结果处理由应用自己的工具系统决定。

7. 下一次请求继续携带已经加载的工具声明，且保持声明内容不变；省略声明后，该工具不再生效，除非别处再次声明。

8. 需要加载新工具时追加到消息末尾；不要修改中间历史或已注入的声明。

9. 检查动态工具消息不含 content，并确认工具对象包含 name、description、parameters 等完整字段。

10. 观察输入 token、缓存读写和调用结果，分别确认工具加载收益与业务执行结果。

原始证据与数据

• 工具定义写在 role="system" 消息的 tools 字段；其格式与请求顶层 tools 相同。

• 动态声明从所在消息的位置起生效，具有普通输入消息的地位；全局工具和动态工具可以共存。

• 动态声明必须是完整定义，不能只传工具名，也不能引用已经在顶层声明的工具。

• 预先声明大量工具会产生 Tool Definition Bloat：描述和参数 schema 增加每次请求的 token，候选工具过多也更容易选错或生成无效参数。

• 动态声明按请求生效，服务端不会自动保留；官方建议后续请求原样带回已加载声明，以维持工具可用性和稳定前缀。

• 每个携带工具的 system 消息都会消耗上下文长度，因此只加载当前对话确实需要的工具。

• 追加声明不会改变已有前缀；修改或插入中间消息会使变化位置之后的缓存失效。缓存按 block 存储，未填满完整 block 的部分不能写入缓存，并按 cache miss 计费。

• 动态工具目前只支持 kimi-k3.1-pro 与 kimi-k3；其他模型（例如 kimi-k2.6）会因 tokenization failed 而失败。

• 带 tools 的 system 消息若同时带 content，请求会返回 400；OpenAI SDK 可直接在 messages 中传 tools，无需 extra_body。

• 本稿未使用 API Key 发起本地或线上 Kimi 请求；没有把静态页面核验写成工具调用成功、延迟或成本实测。

适用边界

• 页面明确的 K3.1 Pro 依据是模型 ID kimi-k3.1-pro 的官方 curl 示例和支持列表；不能把动态加载能力外推给未列出的模型。

• “保留历史”指客户端在后续请求中继续携带已加载声明；文档没有说明服务端自动保存动态工具定义。

• “客户端执行”只覆盖应用插入声明并处理后续调用所需的工作流边界；文档没有规定权限校验、参数校验、超时、重试、并发或工具结果格式。

• 全局工具定义应保持稳定；按需工具适合动态注入。文档说明顶层全局工具不会影响缓存命中，但没有给出固定 token 节省比例。

• 动态加载减少定义开销，不等于工具调用本身免费；system 消息仍计入上下文，缓存命中还受 block 和前缀稳定性影响。

复现说明

1. 打开官方 Dynamically Loaded Tools，确认页面标题及支持模型说明。

2. 使用可用的 Kimi API Key，先声明一个小型顶层工具，再在后续 messages 末尾追加带完整 tools 的 system 消息。

3. 分别测试追加、删除和修改动态声明，核对工具可见位置、后续请求的可调用性及缓存 usage；不要只以 HTTP 200 判断成功。

4. 以 kimi-k3.1-pro 作为模型 ID；不要用页面提到的 kimi-k2.6 作为等价回归模型。

5. 本稿仅记录官方页面公开的流程与限制，未进行本地 API 测试。