使用 Claude 的工具

Claude 能够与外部客户端工具和函数进行交互，让您可以为 Claude 配备自己的自定义工具来执行更多样的任务。

以下是如何使用 Messages API 为 Claude 提供工具的示例:

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-3-7-sonnet-20250219",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?"
      }
    ]
  }'

工具使用的工作原理

通过以下步骤将外部工具与 Claude 集成:

1. 为 Claude 提供工具和用户提示
   • 在您的 API 请求中定义具有名称、描述和输入模式的工具。
   • 包含可能需要这些工具的用户提示，例如”旧金山的天气如何？”
2. Claude 决定使用工具
   • Claude 评估是否有任何工具可以帮助解答用户的查询。
   • 如果是，Claude 会构建一个格式正确的工具使用请求。
   • API 响应的 stop_reason 为 tool_use，表明 Claude 的意图。
3. 提取工具输入、运行代码并返回结果
   • 在您这边，从 Claude 的请求中提取工具名称和输入。
   • 在客户端执行实际的工具代码。
   • 继续对话，发送一个包含 tool_result 内容块的新 user 消息。
4. Claude 使用工具结果来制定响应
   • Claude 分析工具结果以制定对原始用户提示的最终响应。

注意:步骤 3 和 4 是可选的。对于某些工作流程，Claude 的工具使用请求(步骤 2)可能就是您所需要的全部内容，无需将结果发送回 Claude。

工具由用户提供

需要注意的是，Claude 没有任何内置的服务器端工具。所有工具都必须由您(用户)在每个 API 请求中明确提供。这让您可以完全控制和灵活地决定 Claude 可以使用的工具。 计算机使用(测试版)功能是一个例外 - 它引入了由 Anthropic 提供但由您(用户)实现的工具。

​

如何实现工具使用

​

选择模型

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

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

TIP

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

指定工具

工具在 API 请求的顶级参数 tools 中指定。每个工具定义包括:

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

简单工具定义示例

{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

工具使用系统提示

当您使用 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 消息中添加明确的指令。例如:What's the weather like in London? Use the get_weather tool in your response.

​#### JSON 输出

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

​#### 思维链

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

例如，对于提示”What’s the weather like in San Francisco right now, and what time is it there?”，Claude 可能会这样回应:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

这个思维链让我们了解 Claude 的推理过程，可以帮助您调试意外行为。

对于 Claude 3 Sonnet 模型，默认情况下思维链不太常见，但您可以通过在用户消息或系统提示中添加类似”Before answering, explain your reasoning step-by-step in tags.”的内容来提示 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 3.7 Sonnet 的并行工具使用

即使您没有设置 disable_parallel_tool_use，Claude 3.7 Sonnet 在响应中进行并行工具调用的可能性可能较低。为了解决这个问题，我们建议启用令牌高效工具使用，这有助于鼓励 Claude 使用并行工具。 如果您不想选择使用令牌高效工具使用测试版，您也可以引入一个”批处理工具”，它可以作为元工具来同时包装对其他工具的调用。我们发现如果存在这个工具，模型会使用它为您同时并行调用多个工具。 有关如何使用这种解决方法的示例，请参见我们的 cookbook 中的这个示例。

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

当 Claude 决定使用您提供的工具之一时，它会返回一个 stop_reason 为 tool_use 的响应，并在 API 响应中包含一个或多个 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"}])。这些内容块可以使用 text 或 image 类型。
   • is_error(可选): 如果工具执行导致错误，则设置为 true。

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

与其他 API 的区别

与将工具使用分开或使用特殊角色如 tool 或 function 的 API 不同，Anthropic 的 API 将工具直接集成到 user 和 assistant 消息结构中。 消息包含 text、image、tool_use 和 tool_result 块的数组。user 消息包括客户端内容和 tool_result，而 assistant 消息包含 AI 生成的内容和 tool_use。

​

故障排除错误

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

• 工具执行错误
• 超出最大令牌数
• 无效的工具名称
• <search_quality_reflection> 标签

​

工具使用示例

​

定价

工具使用请求的定价与任何其他 Claude API 请求相同，基于发送给模型的输入令牌总数(包括 tools 参数中的)和生成的输出令牌数。

工具使用带来的额外令牌来自:

• API 请求中的 tools 参数(工具名称、描述和模式)
• API 请求和响应中的 tool_use 内容块
• API 请求中的 tool_result 内容块

当您使用 tools 时，我们还会自动包含一个特殊的系统提示，使模型能够使用工具。下面列出了每个模型所需的工具使用令牌数(不包括上面列出的额外令牌)

这些令牌数会加到您的正常输入和输出令牌中，以计算请求的总成本。请参考我们的模型概述表了解当前每个模型的价格。

当您发送工具使用提示时，就像任何其他 API 请求一样，响应将输出输入和输出令牌数作为报告的 usage 指标的一部分。