​
选择模型

通常，对于复杂工具和模糊查询，使用Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5或Claude Opus 3；它们能更好地处理多个工具，并在需要时寻求澄清。

对于简单直接的工具，可以使用Claude Haiku 3.5或Claude Haiku 3，但请注意它们可能会推断缺失的参数。

如果使用Claude Sonnet 3.7进行工具使用和扩展思考，请参考我们这里的指南获取更多信息。

​
指定客户端工具

客户端工具（包括Anthropic定义的和用户定义的）在API请求的顶级参数tools中指定。每个工具定义包括：

参数描述
name工具的名称。必须匹配正则表达式^[a-zA-Z0-9_-]{1,64}$。
description详细的纯文本描述，说明工具的功能、何时应使用以及其行为方式。
input_schema一个JSON Schema对象，定义工具预期的参数。

​
工具使用系统提示

当您使用tools参数调用Anthropic API时，我们会根据工具定义、工具配置和任何用户指定的系统提示构建一个特殊的系统提示。构建的提示旨在指导模型使用指定的工具，并为工具提供正常运行所需的必要上下文：

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

​
工具定义的最佳实践

要在使用工具时获得Claude的最佳性能，请遵循以下指南：

  • 提供极其详细的描述。 这是影响工具性能的最重要因素。您的描述应解释有关工具的每个细节，包括：
    • 工具的功能
    • 何时应使用它（以及何时不应使用）
    • 每个参数的含义及其如何影响工具的行为
    • 任何重要的注意事项或限制，例如如果工具名称不明确，该工具不会返回哪些信息。您能给Claude提供的关于工具的上下文越多，它就越能更好地决定何时以及如何使用它们。每个工具描述至少应有3-4个句子，如果工具复杂，则需要更多。
  • 优先考虑描述而非示例。 虽然您可以在工具描述或附带的提示中包含如何使用工具的示例，但这不如对工具目的和参数有清晰全面的解释重要。只有在充分阐述描述后才添加示例。

良好的描述清楚地解释了工具的功能、何时使用它、它返回什么数据以及ticker参数的含义。糟糕的描述过于简短，让Claude对工具的行为和用法产生许多疑问。

​
控制Claude的输出

​
强制使用工具

在某些情况下，您可能希望Claude使用特定工具来回答用户的问题，即使Claude认为它可以不使用工具就提供答案。您可以通过在tool_choice字段中指定工具来实现这一点，如下所示：

tool_choice = {"type": "tool", "name": "get_weather"}

使用tool_choice参数时，我们有四种可能的选项：

  • auto允许Claude决定是否调用任何提供的工具。这是提供tools时的默认值。
  • any告诉Claude它必须使用提供的工具之一，但不强制使用特定工具。
  • tool允许我们强制Claude始终使用特定工具。
  • none阻止Claude使用任何工具。这是未提供tools时的默认值。

下图说明了每个选项的工作方式：

请注意，当您将tool_choice设置为any或tool时，我们会预填充助手消息以强制使用工具。这意味着即使明确要求，模型也不会在tool_use内容块之前发出链式思考的text内容块。

我们的测试表明，这不应该降低性能。如果您希望保持链式思考（特别是使用Opus）同时仍然要求模型使用特定工具，您可以为tool_choice使用{"type": "auto"}（默认值），并在user消息中添加明确指示。例如：伦敦的天气怎么样？在您的回答中使用get_weather工具。

​
JSON输出

工具不一定需要是客户端函数 — 您可以在任何希望模型返回遵循提供的模式的JSON输出时使用工具。例如，您可能使用具有特定模式的record_summary工具。有关完整的工作示例，请参见工具使用示例。

​
链式思考

使用工具时，Claude通常会展示其”链式思考”，即它用来分解问题并决定使用哪些工具的逐步推理。如果tool_choice设置为auto（这是默认值，请参见强制使用工具），Claude Opus 3模型会这样做，而Sonnet和Haiku可以通过提示来实现这一点。

例如，给定提示”旧金山现在的天气如何，那里现在是几点？“，Claude可能会回应：

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>要回答这个问题，我将：1. 使用get_weather工具获取旧金山的当前天气。2. 使用get_time工具获取America/Los_Angeles时区（覆盖加利福尼亚州旧金山）的当前时间。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

这种链式思考提供了Claude推理过程的洞察，可以帮助您调试意外行为。

对于Claude Sonnet 3模型，默认情况下链式思考不太常见，但您可以通过在用户消息或系统提示中添加类似"在回答之前，在标签中逐步解释您的推理过程。"的内容来提示Claude展示其推理。

重要的是要注意，虽然<thinking>标签是Claude用来表示其链式思考的常见约定，但确切的格式（例如这个XML标签的名称）可能会随时间而变化。您的代码应该将链式思考视为任何其他助手生成的文本，而不依赖于<thinking>标签的存在或特定格式。

​
并行工具使用

默认情况下，Claude可能会使用多个工具来回答用户查询。您可以通过以下方式禁用此行为：

  • 当tool_choice类型为auto时设置disable_parallel_tool_use=true，确保Claude最多使用一个工具
  • 当tool_choice类型为any或tool时设置disable_parallel_tool_use=true，确保Claude恰好使用一个工具

Claude Sonnet 3.7的并行工具使用

Claude Sonnet 3.7在响应中可能不太可能进行并行工具调用，即使您没有设置disable_parallel_tool_use。为了解决这个问题，我们建议启用令牌高效工具使用，这有助于鼓励Claude使用并行工具。这个测试版功能还可以减少延迟，平均节省14%的输出令牌。

如果您不想选择加入令牌高效工具使用测试版，您也可以引入一个”批处理工具”，作为元工具来同时包装对其他工具的调用。我们发现，如果存在这个工具，模型将使用它为您同时并行调用多个工具。

有关如何使用此解决方法的示例，请参见我们cookbook中的这个示例。

​
处理工具使用和工具结果内容块

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度"）或嵌套内容块列表（例如"content": [{"type": "text", "text": "15度"}]）。这些内容块可以使用text或image类型。
    • is_error（可选）：如果工具执行导致错误，则设置为true。

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

​
处理服务器工具的结果

Claude在内部执行工具并直接将结果纳入其响应中，无需额外的用户交互。

与其他API的区别

与分离工具使用或使用特殊角色如tool或function的API不同，Anthropic的API将工具直接集成到user和assistant消息结构中。

消息包含text、image、tool_use和tool_result块的数组。user消息包括客户端内容和tool_result，而assistant消息包含AI生成的内容和tool_use。

​
处理pause_turn停止原因

当使用网络搜索等服务器工具时，API可能会返回pause_turn停止原因，表示API已暂停长时间运行的回合。

以下是处理pause_turn停止原因的方法：

import anthropic

client = anthropic.Anthropic()

# 带有网络搜索的初始请求
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "搜索关于2025年量子计算突破的全面信息"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# 检查响应是否有pause_turn停止原因
if response.stop_reason == "pause_turn":
    # 使用暂停的内容继续对话
    messages = [
        {"role": "user", "content": "搜索关于2025年量子计算突破的全面信息"},
        {"role": "assistant", "content": response.content}
    ]
    
    # 发送继续请求
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

处理pause_turn时：

  • 继续对话：在后续请求中按原样传回暂停的响应，让Claude继续其回合
  • 如需要可修改：如果您想中断或重定向对话，可以选择在继续之前修改内容
  • 保留工具状态：在继续请求中包含相同的工具，以维持功能

​
故障排除错误

使用Claude工具时可能发生几种不同类型的错误：