Claude Platform Docs
Messages工具

处理工具调用

解析 tool_use 块,格式化 tool_result 响应,并使用 is_error 处理错误。

当 Claude 的响应包含 tool_use 块时,您的代码会运行每个工具并发回 tool_result 块,包括任何错误。当您需要对工具执行进行自定义控制时,请自行编写此代码。否则,请使用 SDK 的工具运行器,它会为您运行工具并发送结果。

Claude 的响应会根据它使用的是客户端工具还是服务器工具而有所不同。

处理客户端工具的结果

响应的 stop_reason 为 tool_use,并包含一个或多个 tool_use 内容块,其中包括:

  • id:此特定工具使用块的唯一标识符。稍后将用它来匹配工具结果。
  • name:正在使用的工具的名称。
  • input:一个对象,包含传递给工具的输入,符合工具的 input_schema。

属于 computer use(计算机使用)或 browser use(浏览器使用)工具集成员的 tool_use 块还带有一个 toolset_name 字段("computer" 或 "browser")。其 name 是 Claude 正在调用的成员工具,例如 screenshot 或 navigate,因此请根据这两个字段来分派这些块。

当您收到客户端工具的工具使用响应时,请按以下步骤操作:

  1. 对于每个 tool_use 块,运行该块所指定的工具,并传入其 input。
  2. 在新请求中,保留之前的消息,并将响应的 content 原样作为 assistant 消息添加。
  3. 添加一条 user 消息,为该 content 中的每个 tool_use 块各提供一个 tool_result 块,即使工具执行失败也是如此。
  4. 使用与第一个请求相同的 tools 发送请求。Claude 会使用工具结果继续其响应。
  5. 如果下一个响应的 stop_reason 仍为 tool_use,请重复这些步骤。对于其他值,请参阅停止原因快速参考。

有关这些步骤的完整程序,请参阅教程:构建一个使用工具的智能体。

每个 tool_result 块的 type 都设置为 tool_result,并包含以下字段:

  • tool_use_id:此结果所对应的 tool_use 块的 id。
  • content(可选):工具的结果,可以是字符串或内容块列表。这些内容块可以使用 text、image、document 或 search_result 类型。
  • is_error(可选):如果工具执行失败或调用无效,则设置为 true。

例如,成功的工具结果如下所示:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

回应计算机使用或浏览器使用成员块的 tool_result 还必须回传与 tool_use 块相同的 toolset_name 值;省略该值的成员结果将被拒绝。其 content 的范围也更窄:成员结果只能包含 text 和 image 块,而浏览器使用结果可以额外添加一个 browser_state 块(标签页管理成员仅返回该块)。

处理服务器工具的结果

Claude 在内部运行工具,并将结果直接整合到其响应中,无需额外的用户交互。

使用 is_error 处理错误

当客户端工具执行失败或调用无效时,请发送一个 is_error 设置为 true 的 tool_result 块。Claude 随后可能会通过新的 tool_use 块再次调用该工具,因此请限制您的循环允许的重试次数。

后续步骤

处理 Claude 在单个轮次中调用多个工具的响应。

让 SDK 为您管理 tool_use 循环、结果格式化和重试。

编写能够引导 Claude 选择正确工具的 schema 和描述。

此页面对您有帮助吗?