​
选择模型

通常，对于复杂工具和模糊查询，使用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时，我们会从工具定义、工具配置和任何用户指定的系统提示构建一个特殊的系统提示。构建的提示旨在指导模型使用指定的工具并为工具正常运行提供必要的上下文：

在此环境中，您可以访问一组工具来回答用户的问题。
{{ 格式化说明 }}
字符串和标量参数应按原样指定，而列表和对象应使用JSON格式。请注意，字符串值的空格不会被删除。输出不需要是有效的XML，而是用正则表达式解析。
以下是JSONSchema格式的可用函数：
{{ JSON SCHEMA格式的工具定义 }}
{{ 用户系统提示 }}
{{ 工具配置 }}

​
工具定义的最佳实践

要在使用工具时获得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参数的更改将使缓存的消息块失效。工具定义和系统提示保持缓存，但消息内容必须重新处理。

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

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

在工具使用中使用扩展思考时，不支持tool_choice: {"type": "any"}和tool_choice: {"type": "tool", "name": "..."}，会导致错误。只有tool_choice: {"type": "auto"}（默认值）和tool_choice: {"type": "none"}与扩展思考兼容。

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

​
JSON输出

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

​
思维链

使用工具时，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 4模型默认具有出色的并行工具使用能力，但您可以通过有针对性的提示来增加所有模型并行工具执行的可能性：

Claude Sonnet 3.7的并行工具使用

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

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

请参阅我们cookbook中的此示例了解如何使用此解决方法。

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

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

​
处理客户端工具的结果

响应将有一个tool_use的stop_reason和一个或多个tool_use内容块，包括：

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

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

  1. 从tool_use块中提取name、id和input。
  2. 在您的代码库中运行与该工具名称对应的实际工具，传入工具input。
  3. 通过发送一个role为user的新消息继续对话，内容块包含tool_result类型和以下信息：
    • tool_use_id：这是工具使用请求的结果的id。
    • content：工具的结果，作为字符串（例如"content": "15度"）或嵌套内容块列表（例如"content": [{"type": "text", "text": "15度"}]）。这些内容块可以使用text或image类型。
    • is_error（可选）：如果工具执行导致错误，设置为true。

重要的格式要求：

  • 工具结果块必须紧跟在消息历史中相应的工具使用块之后。您不能在助手的工具使用消息和用户的工具结果消息之间包含任何消息。
  • 在包含工具结果的用户消息中，tool_result块必须在内容数组中排在第一位。任何文本都必须在所有工具结果之后。

例如，这将导致400错误：

{"role": "user", "content": [
  {"type": "text", "text": "这是结果："},  // ❌ tool_result之前的文本
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

这是正确的：

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "我接下来应该做什么？"}  // ✅ tool_result之后的文本
]}

如果您收到类似”在tool_use ids之后立即找到了没有tool_result块的错误”，请检查您的工具结果格式是否正确。

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

​
处理服务器工具的结果

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

与其他API的差异

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

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

​
处理max_tokens停止原因

如果Claude的响应由于达到max_tokens限制而被截断，并且截断的响应包含不完整的工具使用块，您需要使用更高的max_tokens值重试请求以获得完整的工具使用。

# 检查响应是否在工具使用期间被截断
if response.stop_reason == "max_tokens":
    # 检查最后一个内容块是否是不完整的tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # 使用更高的max_tokens发送请求
        response = client.messages.create(
            model="claude-opus-4-20250514",
            max_tokens=4096,  # 增加限制
            messages=messages,
            tools=tools
        )

​
处理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工具时可能出现几种不同类型的错误：