处理工具调用

本页介绍工具调用的生命周期：从 Claude 的响应中读取 tool_use 块、在您的回复中格式化 tool_result 块，以及发出错误信号。如需了解自动处理这些操作的 SDK 抽象层，请参阅 Tool Runner。

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



处理客户端工具的结果

响应的 stop_reason 将为 tool_use，并包含一个或多个 tool_use 内容块，其中包括：

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

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

1. 从 tool_use 块中提取 name、id 和 input。
2. 在您的代码库中运行与该工具名称对应的实际工具，并传入工具的 input。
3. 通过发送一条 role 为 user 的新消息来继续对话，该消息包含一个 tool_result 类型的 content 块以及以下信息：
   • 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": "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 一起使用工具时，可能会发生几种不同类型的错误：



后续步骤