Kimi K3.1 Pro 工具调用执行循环：Schema、JSON 参数与 tool_call_id 回传

一句话结论

工具调用的闭环是：提交 JSON Schema 工具定义，读取 finish_reason=tool_calls 的调用列表，解析每个 function.arguments，由客户端执行，再用匹配的 tool_call_id 追加 role="tool" 结果，直到模型返回 finish_reason=stop。

适用场景

• 适合的任务：搜索、数据库查询、网页抓取和其他由客户端执行的多步 Agent 工具流程。

• 不适合的任务：希望模型直接执行本地函数，或把未执行的工具调用当作最终答案的请求。

• 适用的模型版本：页面当前示例默认使用 kimi-k3.1-pro；页面还提到可替换为 kimi-k3.1-pro-highspeed，但本稿没有把 Highspeed 当作等价实测版本。

• 适用的客户端、Agent 或 API：Kimi API Chat Completions；官方示例使用 OpenAI Python SDK 或 HTTP 流式响应，由应用自己执行工具。

• 推荐的推理档位和参数：K3.1 Pro 的 reasoning_effort 放在请求顶层，可选 low、high、max，默认 max；工具闭环本身不规定必须使用某个档位。

可直接使用的内容

下面是官方格式的最小化改写，用于定义一个搜索工具；它是工作流片段，不是可独立运行的完整 prompt：

{
  "type": "function",
  "function": {
    "name": "search",
    "description": "Search the internet for the user's query.",
    "parameters": {
      "type": "object",
      "required": ["query"],
      "properties": {
        "query": {
          "type": "string",
          "description": "The content to search for."
        }
      }
    }
  }
}

请求时把一个或多个这样的对象放入顶层 tools。模型返回的 function.arguments 是序列化 JSON 对象，客户端必须反序列化后再分发：

assistant = completion.choices[0].message
if completion.choices[0].finish_reason == "tool_calls":
    messages.append(assistant)  # 保留包含 tool_calls 的 assistant 消息
    for call in assistant.tool_calls:
        args = json.loads(call.function.arguments)
        result = tool_map[call.function.name](args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "name": call.function.name,
            "content": json.dumps(result),
        })

测试或工作流步骤

1. 为每个客户端真实可执行的函数写 JSON Schema，parameters.type 固定为 object，并列出 required 与 properties。

2. 给工具填写清晰的 description，说明作用和调用条件；函数名使用英文字符、数字、连字符和下划线。

3. 首次请求把一个或多个工具放在顶层 tools，并保留当前 messages。

4. 读取 choices[0].finish_reason。为 tool_calls 时，message.content 可能为空，也可能只解释将调用哪些工具。

5. 遍历 message.tool_calls，用 function.name 查找客户端的工具映射，用 json.loads(function.arguments) 解析参数。

6. 执行每个客户端函数；工具的权限、参数校验、超时和错误处理由应用负责，模型不会替应用执行函数。

7. 把 API 返回的 assistant 消息先原样加入 messages，再为每个调用追加一条 role="tool" 消息。

8. 每条工具结果必须携带对应的 tool_call_id 和工具名，结果正文用字符串传回，JSON 结果可用 json.dumps 序列化。

9. 多个互不依赖的调用可以并发执行；官方循环示例按列表逐个执行，但每个结果仍要独立匹配自己的 ID。

10. 将完整历史再次提交给 API；若新的 finish_reason 仍为 tool_calls，继续循环，否则在 stop 时返回最终 message.content。

11. 流式模式下以 delta.tool_calls 判断调用，不要等到最后一个数据块才首次识别；先累积内容，再处理工具调用字段。

12. 流式响应通常在初始数据块给出 id、type、函数名，后续数据块追加 function.arguments；多个调用用 index 分桶并分别拼接。

13. 拼接完每个调用的参数字符串后再做 JSON 解析和执行；收到 [DONE] 后结束流式读取。

原始证据与数据

• 工具定义的固定外层结构是 type="function"、function.name、function.description 和 function.parameters；参数 Schema 使用 JSON Schema。

• tools 可以一次提交多个工具，模型可以不调用工具，也可以返回多个不同工具或同一工具的多个调用。

• 非流式调用示例的调用对象包含唯一 id、type="function" 和 function.name；function.arguments 是有效的序列化 JSON 对象。

• finish_reason="tool_calls" 表示当前响应是要执行的工具，而不是给用户的最终答案；工具结果回传后，模型通常在 finish_reason="stop" 时生成最终答复。

• 官方执行循环把 choice.message 追加到历史，再逐个执行 tool_calls，把工具结果以 role="tool"、tool_call_id、name 和字符串 content 追加回去。

• 当一次返回多个调用时，必须让每个 tool_call 都有一条匹配的 role="tool" 消息；数量不符或 ID 无法匹配都会报错。

• 流式模式的 delta.tool_calls 需要按 index 合并；参数片段像 delta.content 一样分块到达，不能把单个片段直接当作完整 JSON。

• 文档说明 function_call 及相关旧参数已不再支持，应使用 tool_calls；tool_calls 还支持并行调用。

• tools 定义本身计入总 token，工具定义与消息合计不能超过模型上下文窗口。

• 页面明确写出当前示例默认模型为 kimi-k3.1-pro，但函数执行、并行返回和流式拼接是 API 工具调用流程的文档说明；不能据此声称本稿完成了线上 K3.1 Pro 实测。

适用边界

• 本文的 K3.1 Pro 依据是该页面当前代码示例中的 model="kimi-k3.1-pro" 及页面对默认模型的说明；页面中可替换的 Highspeed 变体没有在本稿中单独验证。

• “客户端执行”指应用根据模型生成的函数名和参数调用自己的实现；API 文档没有替应用完成网络请求、权限控制、参数安全校验、重试或超时策略。

• 官方示例用 search、crawl 和占位的搜索接口展示流程；这些接口不是 Kimi 内置工具，也不证明任何具体搜索服务已连通。

• 多个工具结果可并行准备，但回传仍须一一对应 tool_call_id；并行执行顺序、失败重试和部分失败策略需要客户端自行设计。

• 如果漏掉 API 返回的 assistant 消息，或其中的 tool_calls 字段不完整，下一次提交可能出现 tool_call_id not found；保留该消息是 ID 匹配要求，不是本文对 P03 思考历史的重复讨论。

• 文档说明流式字段的组装方式，但没有给出 K3.1 Pro 的延迟、吞吐、工具成功率或成本数据；本文未使用 API Key 发起调用。

复现说明

1. 打开官方 Use Kimi API for Tool Calls，确认页面标题、默认模型说明和工具调用章节。

2. 使用可用的 Kimi API Key，以 model="kimi-k3.1-pro"、tools=[...] 发起一次 Chat Completions 请求；不要把页面静态示例当作已完成的线上验证。

3. 记录返回的 finish_reason、每个 tool_calls[].id、函数名和完整 arguments，先用 JSON 解析，再执行测试工具。

4. 原样追加 assistant 消息，为每个调用追加匹配的 role="tool" 消息，继续请求直到返回 finish_reason="stop"。

5. 另用 stream=true 检查 delta.tool_calls、index 和分块参数拼接；分别验证单个调用、多个调用、无工具调用和工具错误路径。

6. 核对工具结果数量与 ID 映射；记录请求、工具执行和最终回复，但不要把 API Key、用户原文或敏感工具参数写入日志。

7. 本稿仅记录官方文档公开的 schema 和执行循环，未声称 K3.1 Pro 的本地或线上实测结果。