Messages工具
工具使用故障排查
通过症状到修复的诊断表格,修复最常见的工具使用错误。
找到您遇到的症状或错误,然后应用为其列出的修复方法。
Claude 调用了错误的工具
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 您想要工具 B,但 Claude 调用了工具 A | 描述含糊不清 | 使描述更加精确。通过"何时"使用工具来区分它们,而不仅仅是它们"做什么"。请参阅定义工具。 |
| Claude 从不调用您的工具 | 工具名称冲突或 schema 过于笼统 | 检查工具列表中是否存在重复名称。添加 input_examples 以使预期用法更加具体。 |
| Claude 调用时使用了错误的参数类型 | schema 存在歧义 | 添加 strict: true(如果您的 schema 属于受支持的子集)或添加 input_examples。 |
Claude 编造工具参数
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 出现了您的 schema 中不存在的参数 | 未启用严格模式时模型过度生成 | 如果您的 schema 属于受支持的子集,请添加 strict: true。 |
| 参数值超出您的枚举范围 | 缺少严格模式或枚举过大 | 缩小枚举范围,或添加展示有效选项的 input_examples。 |
并行工具调用不起作用
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 在并行更合适的情况下,Claude 却按顺序调用工具 | 消息历史格式问题 | 在一条用户消息中发送多个 tool_result 块,而不是每轮发送一个。请参阅并行工具使用。 |
disable_parallel_tool_use 似乎被忽略 | 在对话中设置得太晚 | 在返回 tool_use 的请求上设置它。在后续请求上设置它对之前的工具调用没有影响。 |
缓存不断失效
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 每个请求都是缓存未命中 | tool_choice、思考配置或 output_config.effort 在请求之间发生变化 | 保持 tool_choice 稳定,或将 cache_control 断点放在变化点之前;在缓存对话的整个生命周期内保持思考配置和 effort 级别不变。请参阅工具使用与提示缓存和思考与提示缓存。 |
| 在对话中途添加工具会破坏缓存 | 工具被添加到 tools 数组的开头 | 从第一个请求起就使用 defer_loading: true 声明该工具,并让工具搜索以内联方式加载它,而不是稍后再将其添加到数组中。 |
请求时的错误
"错误"列显示每条消息的一部分,... 代表可变的文本。
| 错误 | 原因 | 修复方法 |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | 某些 tool_use ID 缺少 tool_result,或 tool_result 不是用户消息中的第一个内容块 | 为助手响应中的每个 tool_use 块返回一个 tool_result。将 tool_result 块放在任何文本之前。请参阅处理工具调用和并行工具使用。 |
was found without a corresponding ... block | 后续请求阻止了一个等待中的服务器工具运行 | 请参阅服务器工具调用没有结果块。 |
Unsupported regex feature in pattern field: ... | 严格工具的 pattern 使用了严格模式无法编译的正则表达式特性,例如反向引用、单词边界或较大的 {n,m} 范围 | 简化该模式。请参阅 JSON Schema 限制。 |
Invalid regex in pattern field: ... | 严格工具的 pattern 包含先行断言、后行断言或语法错误 | 删除所有先行断言或后行断言,并修复所有语法错误。请参阅 JSON Schema 限制。 |
All tools have defer_loading: true | 没有对模型可见的工具 | 至少必须有一个工具被立即加载。工具搜索工具本身绝不能设置 defer_loading: true。 |
服务器工具调用没有结果块
当服务器工具的 server_tool_use 或 mcp_tool_use 块没有结果块时,该工具仍在等待运行。错误 was found without a corresponding ... block 表示后续请求阻止了该等待中的工具运行。错误消息和上一个 stop_reason 会说明原因。请采用第一个匹配的情况:
- 消息以
but no `<name>` tool was provided或is not available after the last message结尾: 此处的<name>是工具的名称,例如web_search。请求不再定义该工具。请发送与之前相同的tools数组;对于 MCP 工具,还需发送相同的mcp_servers。 - 上一个
stop_reason是tool_use: 您的用户消息在tool_result块之后还有其他内容。请仅发送tool_result块,每个客户端tool_use块对应一个。 - 上一个
stop_reason是pause_turn: 您添加了一条用户消息。请将其删除,使请求以作为assistant消息的已暂停响应结尾。
有关完整步骤,请参阅当服务器工具仍在等待时和 pause_turn 停止原因。
错误:思考块无法修改
如果在工具调用后继续对话时,请求失败并返回 400 invalid_request_error,且其消息包含 `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified,则说明您的应用程序在将助手的思考块发回之前对其进行了修改。请将整条助手消息原样发回,然后追加您的 tool_result。
请参阅思考块无法修改了解完整的错误信息和修复步骤。
Claude 将工具结果标记为提示注入
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| Claude 拒绝根据工具结果采取行动,或要求用户确认来自工具结果的指令 | 您自己的指令被放在 tool_result 内容中传递 | Claude 经过训练,会将工具结果中的指令视为可能不受信任的第三方内容。请将您的指令移出工具结果:在 tool_result 块之后的 user 轮次中发送它们,或者在受支持的模型上,通过对话中途的系统消息发送。让工具结果仅包含数据。请参阅缓解越狱和提示注入。 |
不同模型版本之间的 JSON 转义差异
| 症状 | 原因 | 修复方法 |
|---|---|---|
| 在较新的模型上,对工具输入进行字符串比较失败 | 不同模型版本之间的 Unicode 和正斜杠转义方式不同 | 使用 json.loads() 或 JSON.parse() 进行解析。切勿对序列化后的输入进行原始字符串匹配。 |
后续步骤
此页面对您有帮助吗?