处理工具调用
解析 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" }
}
]
}当您收到客户端工具的工具使用响应时,请按以下步骤操作:
- 对于每个
tool_use块,运行该块所指定的工具,并传入其input。 - 在新请求中,保留之前的消息,并将响应的
content原样作为assistant消息添加。 - 添加一条
user消息,为该 content 中的每个tool_use块各提供一个tool_result块,即使工具执行失败也是如此。 - 使用与第一个请求相同的
tools发送请求。Claude 会使用工具结果继续其响应。 - 如果下一个响应的
stop_reason仍为tool_use,请重复这些步骤。对于其他值,请参阅停止原因快速参考。
有关这些步骤的完整程序,请参阅教程:构建一个使用工具的智能体。
每个 tool_result 块的 type 都设置为 tool_result,并包含以下字段:
tool_use_id:此结果所对应的tool_use块的id。content(可选):工具的结果,可以是字符串或内容块列表。这些内容块可以使用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 在内部运行工具,并将结果直接整合到其响应中,无需额外的用户交互。
使用 is_error 处理错误
当客户端工具执行失败或调用无效时,请发送一个 is_error 设置为 true 的 tool_result 块。Claude 随后可能会通过新的 tool_use 块再次调用该工具,因此请限制您的循环允许的重试次数。
如果工具本身在执行过程中抛出错误(例如,获取天气数据时出现网络错误),您可以在 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 可以再次调用该工具,或告知用户发生了什么。例如,Claude 可能会说:"抱歉,由于天气服务 API 不可用,我无法获取当前天气。请稍后再试。"
如果 Claude 对工具的尝试使用无效(例如,缺少必需参数),通常意味着 Claude 没有足够的信息来正确使用该工具。在开发过程中,最佳做法是在工具定义中使用更详细的 description 值重新尝试请求。
不过,您也可以通过一个指示错误的 tool_result 继续对话:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}然后 Claude 可以补全缺失的信息后再次调用该工具。
与客户端工具不同,您无需为服务器工具发送 is_error 结果。当服务器工具遇到错误时(例如网络搜索期间出现网络问题),API 会在该工具的结果块中返回错误。在大多数情况下,Claude 随后会改用其他方法继续,或向用户提供解释。
有关网页搜索的错误代码,请参阅网页搜索工具错误。
后续步骤
处理 Claude 在单个轮次中调用多个工具的响应。
让 SDK 为您管理 tool_use 循环、结果格式化和重试。
编写能够引导 Claude 选择正确工具的 schema 和描述。
此页面对您有帮助吗?