处理工具调用

解析 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,因此请根据这两个字段来分派这些块。

示例代码
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-5-5",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA", "unit": "celsius" }
    }
  ]
}

当您收到客户端工具的工具使用响应时,您应该:

  1. 从 tool_use 块中提取 name、id 和 input。

  2. 在您的代码库中运行与该工具名称对应的实际工具,并传入工具的 input。

  3. 通过发送一条 role 为 user 的新消息来继续对话,其中的 content 块包含 tool_result 类型和以下信息:

    • tool_use_id:此结果所对应的工具使用请求的 id。
    • content(可选):工具的结果,可以是字符串(例如 "content": "15 degrees")、嵌套内容块列表(例如 "content": [{"type": "text", "text": "15 degrees"}])或文档块列表(例如 "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}])。这些内容块可以使用 text、image、document 或 search_result 类型。
    • is_error(可选):如果工具执行导致错误,则设置为 true。

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

示例代码
{
  "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 块(标签页管理成员仅返回该块)。

示例代码
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        { "type": "text", "text": "15 degrees" },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg..."
          }
        }
      ]
    }
  ]
}
示例代码
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9"
    }
  ]
}
示例代码
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        { "type": "text", "text": "The weather is" },
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 degrees"
          }
        }
      ]
    }
  ]
}

例如,以下写法会导致 400 错误:

示例代码
{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

当助手轮次仅调用客户端工具时,以下内容是正确的:

示例代码
{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

收到工具结果后,Claude 将使用该信息继续生成对原始用户提示的响应。

处理服务器工具的结果

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

使用 is_error 处理错误

在 Claude 中使用工具时,可能会出现几种不同类型的错误:

如果工具本身在执行过程中抛出错误(例如,获取天气数据时出现网络错误),您可以在 content 中返回错误消息,并附带 "is_error": true:

示例代码
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

然后 Claude 会将此错误整合到其对用户的响应中。例如:"抱歉,由于天气服务 API 不可用,我无法获取当前天气。请稍后再试。"

如果 Claude 对工具的尝试使用无效(例如,缺少必需参数),通常意味着 Claude 没有足够的信息来正确使用该工具。在开发过程中,最佳做法是在工具定义中使用更详细的 description 值重新尝试请求。

不过,您也可以通过一个指示错误的 tool_result 继续推进对话,Claude 将尝试补全缺失的信息后再次使用该工具:

示例代码
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

如果工具请求无效或缺少参数,Claude 会在修正后重试 2–3 次,然后再向用户致歉。

当服务器工具遇到错误时(例如,网络搜索出现网络问题),Claude 会透明地处理这些错误,并尝试向用户提供替代响应或解释。与客户端工具不同,您无需为服务器工具处理 is_error 结果。

具体就网页搜索而言,可能的错误代码包括:

  • too_many_requests:超出速率限制
  • invalid_input:无效的搜索查询参数
  • max_uses_exceeded:超出网页搜索工具的最大使用次数
  • query_too_long:查询超出最大长度
  • unavailable:发生内部错误

后续步骤

定义工具

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

文档内容持续同步更新