Claude 工具调用报错的消息排序排查
Claude 原生 Messages API 要求工具结果紧跟工具调用,放入下一条用户消息,准确匹配调用 ID,并排列在文本之前。并行调用的结果需一起返回,使用网关时还应确认其是否遵循原生格式校验。
AI 深度解读
Claude 调工具时报 400,先别急着改提示词。原文讨论的是一个更具体的问题:工具已经执行,结果也拿到了,但应用把 tool_result 放错了位置,或者配错了调用 ID,导致后续请求被拒绝。修复重点在会话历史的组装方式。
这篇指南值得读的地方,还在于它划清了两件事:消息缺少结果,不代表工具没执行;原生 Anthropic Messages 的规则,也不能直接当成所有网关的验收标准。前者关系到重复操作,后者决定你有没有查对问题。
工具结果为什么必须紧跟上一条调用
原文针对的是 Claude 原生 Messages API 中的客户端工具调用:模型发出调用,应用负责执行,再把结果交回模型。
它的消息结构有明确约束。tool_use 放在 assistant 消息里,对应的 tool_result 放在紧接着的下一条 user 消息里,不另建一个 tool 角色。结果中的 tool_use_id 必须与调用的 id 完全一致,每次调用恰好对应一个结果。
下面这段三条消息的示例,展示了完整的工具往返:
[
{"role": "user", "content": "What is the weather in Paris?"},
{
"role": "assistant",
"content": [
{"type": "tool_use", "id": "toolu_demo_1", "name": "get_weather", "input": {"location": "Paris"}}
]
},
{
"role": "user",
"content": [
{"type": "tool_result", "tool_use_id": "toolu_demo_1", "content": "12 C, cloudy"}
]
}
]
要盯住的是最后一条消息的 tool_use_id:它复制的是上一条调用的实际 ID,不能由应用重新生成。toolu_demo_1 只是示例。
位置也不能随意调整。所有结果块必须排在该条 user 消息的文本之前,不能先写一句「查询完成」,再追加结果。对于只涉及客户端工具的这一轮,可以把说明文字放在全部结果后面,或者留到后续消息。
如果同一轮还启动了尚未完成的服务端工具,规则更严格:客户端回复只能包含客户端的 tool_result,不能附加会结束这一轮的文本。服务端工具有自己的响应生命周期,也不能替它编造客户端结果。
因此,遇到原文给出的 400 错误 tool_use ids were found without tool_result blocks immediately after,第一步应该检查实际发出的历史:调用之后的下一条消息,是否已经完整带回对应结果。
多个工具一起调用,执行顺序和结果配对要分开
Claude 一次可以返回多个 tool_use。应用可以并行执行,也可以顺序执行;按照原文转述的 Anthropic 规则,API 不规定这些工具的执行次序。
独立的只读查询适合并行。涉及共享状态、副作用或先后依赖的操作,往往需要顺序处理。但无论怎么执行,同一条 assistant 消息发出的调用,都要在下一条 user 消息里一起交回结果。
下面的例子故意把时间结果排在天气结果前面:
[
{"role": "assistant", "content": [
{"type": "tool_use", "id": "toolu_demo_weather", "name": "get_weather", "input": {"location": "Paris"}},
{"type": "tool_use", "id": "toolu_demo_time", "name": "get_time", "input": {"timezone": "Europe/Paris"}}
]},
{"role": "user", "content": [
{"type": "tool_result", "tool_use_id": "toolu_demo_time", "content": "14:30 CEST"},
{"type": "tool_result", "tool_use_id": "toolu_demo_weather", "content": "12 C, cloudy"}
]}
]
关键仍是两行 tool_use_id。结果数组可以与调用数组顺序不同,只要各自指向正确调用;如果应用内部另外依赖固定顺序,也需要保持自身约定一致。
用 ID 配对结果,不要用数组下标猜测归属。
异步任务完成顺序可能改变。按「第一个完成的结果对应第一个调用」拼装消息,有可能把时间交给天气工具,而且不一定立刻触发格式错误。
原文还给出一个 Python 本地预检函数 check_tool_result_pairs(messages),检查相邻消息、结果数量、ID 是否为空或重复,以及结果前面是否混入其他内容。它也会拒绝找不到前置调用的孤立结果。
这个检查适合放在续传请求之前,但它只验证简化的客户端工具消息结构,不检查工具 schema、服务端工具生命周期、特殊工具集或网关转换。通过本地检查,不等于远端一定接受。
工具失败要交结果,进程中断要先查执行状态
工具执行失败与消息格式错误,是两类问题。
工具已经运行但报错,仍然需要返回对应的 tool_result,设置 is_error: true,并解释失败原因和可继续采取的动作。应用主动跳过某个调用,也不能直接遗漏它,应该返回对应的错误结果,让这一轮调用有明确交代。
进程中断则更棘手。假设应用已经发出预订请求,却在把结果写入会话历史之前退出。恢复后,历史里没有结果,但远端可能已经完成预订。
缺少 tool_result,不能作为重新执行副作用操作的依据。
原文建议先查持久化调用记录,使用提供方或工具请求 ID、幂等键,或者应用状态核对结果。能恢复结果,就把它关联到原来的 tool_use_id;无法确认,则如实报告失败或结果未知。没有查询或安全去重手段时,应暂停核对,而不是猜测执行状态。
这条原则同样适用于支付、删除、邮件等非幂等操作。会话记录负责告诉模型发生了什么,执行记录负责确认业务实际发生了什么,两者不能互相替代。
回放会话时,也要保留收到的 assistant 内容,尤其是包含 thinking 块的响应。不能只摘出 tool_use,重新拼一个看似等价的消息。保留响应块与补齐工具结果,是两项独立的协议要求。
我的判断
我认同这篇指南的排查顺序:先确认消息结构,再区分执行失败与状态丢失,最后检查网关协议。它把一个容易被归咎于模型的错误,落到了可以检查的请求数据上。
但原文的证据边界必须保留。作者明确说明,没有进行真实 Tokenhot 请求,也没有完成端到端工具运行;天气、时间和调用 ID 都是假设示例。本地预检只能检查形状,不能证明远端兼容性。这是一份协议排障指南,不能当成 Tokenhot 路由的实测报告。
原文列出的入口是 POST https://api.tokenhot.ai/v1/messages,模型代码包括 claude-sonnet-5、claude-opus-4-6、claude-opus-4-8。这些是原文所列信息,不能据此推断其当前可用性或具体映射。作者也承认,路由页面只有基础消息示例,没有说明多工具历史的校验行为。
相比凭错误文案反复重试,检查实际出站请求更有针对性;相比直接套用原生规则,先识别网关是否采用 OpenAI-compatible 转换协议,也更稳妥。路径看起来相似,不足以证明消息约定相同。
至于预检能减少多少错误、增加多少维护成本,作者没有给对照数据。它作为工程防线有道理,收益仍需团队自己验证。
能拿来做什么
- 在 Node 工具调用服务发出续传请求前,检查相邻消息、ID 唯一性、一对一配对,以及结果块是否位于文本之前;检查对象应是最终出站历史。
- 在日常 AI 编程工具的编排层,按
tool_use.id收集结果,等同一轮调用都有交代后统一返回;失败或主动跳过的调用也要生成明确结果。 - 对删除、预订、发邮件等工具,单独保存执行状态和可用的幂等信息,恢复任务时先核对业务结果,再决定是否重试。
- 接入网关后若仍被拒绝,先确认实际协议,再保存原始请求及响应 ID;提交排障样例前去掉凭证和私密内容,并向提供方核对具体路由与模型代码。