标签：Kimi API、Agent 开发、Function Call、工具调用排坑
最近在对接 Kimi 的 Function Call 工具调用时，高频碰到报错：tool_call_id is not found。 这个报错和 OpenAI 兼容模式宽松的校验逻辑完全不一样，Kimi 是基于会话消息链做强绑定校验，不是简单比对字符串，很多人踩坑就是沿用了 OpenAI 的旧写法。
核心原理
Kimi 的校验逻辑一句话总结：
当前消息数组
messages中，必须提前存在对应的 assistant 消息，这条消息携带tool_calls，里面的tool_call.id，和后续role=tool消息里的tool_call_id必须完全一致。在消息链里找不到这个 ID 对应的 assistant 记录，直接抛出tool_call_id is not found。
它不是只校验字符串格式，而是沿着你传入的 messages 上下文回溯查找归属的工具调用记录。
高频 4 个踩坑原因（按出现概率排序）
1. 只提取 tool_calls，没有把 assistant 消息加入消息列表（最高发）
收到 finish_reason="tool_calls" 的返回之后，很多开发者只取出里面的 tool_calls 去执行工具，忘记把这条原始 assistant 消息 push 进 messages 数组。 没有这条 assistant 记录，后续回填 tool 结果时，Kimi 在上下文里找不到这个 ID，直接报错。
❌ 错误做法：只保存 id，不存入 assistant 消息 ✅ 正确做法：先追加完整的 assistant 消息，再追加 tool 结果消息
2. 修改、清洗、格式化 tool_call_id，字符串不严格全等
Kimi 原生生成的 tool_call id 经常包含下划线、随机字符。 如果代码里做正则过滤、字符清洗、截断、自定义生成 ID，都会导致字符串不匹配。
重点：tool_call_id 必须原样取用 Kimi 返回的 id，不要做任何修改，大小写、符号、长度都不能变。
3. 一次返回多个 tool_calls，工具结果数量不匹配
当一轮 assistant 返回 N 个并行工具调用，你必须提供 N 条 role=tool 的消息，一一绑定对应的 id。 少一条、多一条、id 映射错乱，都会触发校验失败。顺序不强制，但 ID 映射关系必须完整。
4. Stream 流式模式下，tool_calls 分片拼接错误
流式返回时，tool_calls 的内容会分散在多个 delta chunk 中，id 有可能分段下发。 如果没有等流结束、组装完整 tool_calls 对象就直接入栈或者回填工具结果，会得到残缺、错误的 id。
流式场景建议：等待本轮 stream 全部结束，合并组装完成完整 tool_calls 之后，再把 assistant 消息入消息栈，再执行工具、回填结果。
标准合法消息序列模板
[
{"role":"system","content":"系统提示词"},
{"role":"user","content":"用户提问"},
// 【必须保留】Kimi 返回的 assistant 消息，携带 tool_calls
{
"role":"assistant",
"content":"",
"tool_calls": [
{
"id": "call_abc123xyz",
"function": {
"name": "search",
"arguments": "{\"query\":\"xxx\"}"
}
}
]
},
// 【工具结果回填】tool_call_id 和上面的 id 严格一致
{
"role":"tool",
"tool_call_id": "call_abc123xyz",
"content":"这里是工具返回的结果"
}
]
快速排查清单
- ✅ 打印完整 messages，确认携带
tool_calls的 assistant 消息在 tool 消息前面 - ✅ 做全等字符串对比：
tool_call.id === tool_call_id，不做清洗、转义 - ✅ 流式场景：等全部 delta 接收完毕，合并出完整 tool_calls 再入栈
- ✅ 不要在 assistant (tool_calls) 和 tool 结果中间插入 user 消息，破坏配对上下文
- ✅ 并发多工具调用：每个 tool_call 独立绑定本轮 assistant，禁止跨轮复用 tool_call_id
和 OpenAI 兼容模式的关键区别
OpenAI 的校验相对宽松，很多场景下只需要 id 字符串对上即可； Kimi 是强会话上下文检索校验，会在你传入的整条 messages 链里面查找这个 ID 归属的 assistant 工具调用记录。沿用 OpenAI 的 Agent 代码直接对接 Kimi，大概率踩这个坑。
小结
tool_call_id is not found 本质不是 ID 格式错误，是消息链配对丢失。 记住两条铁律：
- 所有带 tool_calls 的 assistant 消息，一定要原样存入 messages；
- 回填 tool 消息时，id 原样复制，不修改、不生成、不清洗。
