工具使用（函数调用）

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

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

​

工具使用的工作原理

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

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

​

如何实现工具使用

​

选择模型

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

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

​

指定工具

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

{
  "name": "get_weather",
  "description": "获取指定位置的当前天气",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "城市和州，例如 San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "温度单位，可以是 'celsius' 或 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

工具使用系统提示

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

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

​

工具定义的最佳实践

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

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

{
  "name": "get_stock_price",
  "description": "获取给定股票代码的当前股票价格。股票代码必须是在纽约证券交易所或纳斯达克等主要美国证券交易所上市的公司的有效代码。该工具将返回最新的交易价格（以美元为单位）。当用户询问特定股票的当前或最近价格时应使用它。它不会提供有关股票或公司的任何其他信息。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "股票代码，例如 AAPL 代表苹果公司"
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "获取股票代码的股票价格。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

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

​

控制 Claude 的输出

​

强制使用工具

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

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

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

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

此图说明了每个选项的工作原理：

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

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

​

JSON 输出

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

​

思维链

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

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

{
  "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 3 Sonnet 模型，默认情况下思维链不太常见，但您可以通过在用户消息或系统提示中添加类似 "在回答之前，请在标签中逐步解释您的推理。" 的内容来提示 Claude 显示其推理。

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

​

禁用并行工具使用

默认情况下，Claude 可能会使用多个工具来回答用户查询。您可以通过在 tool_choice 字段中设置 disable_parallel_tool_use=true 来禁用此行为。

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

​

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

当 Claude 决定使用您提供的工具之一时，它将返回一个 stop_reason 为 tool_use 的响应，以及 API 响应中的一个或多个 tool_use 内容块，其中包括：

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

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>我需要使用 get_weather，用户想要了解 SF，这很可能是指旧金山，加利福尼亚州。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

当您收到工具使用响应时，您应该：

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。

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 度"
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 度"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
    }
  ]
}

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

​

故障排除错误

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: 天气服务 API 不可用（HTTP 500）",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "错误：缺少必需的 'location' 参数",
      "is_error": true
    }
  ]
}

​

工具使用示例

以下是演示各种工具使用模式和技术的几个代码示例。为了简洁起见，这些工具都是简单工具，工具描述也比确保最佳性能所需的要短。

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>我需要调用 get_weather 函数，用户想要了解 SF，这很可能是指旧金山，加利福尼亚州。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "旧金山当前的天气是 15 度摄氏度（59 度华氏度）。这是海湾城市一个凉爽的日子！"
    }
  ]
}

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

​

定价

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

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

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

当您使用 tools 时，我们还会自动为模型包含一个特殊的系统提示，以启用工具使用。每个模型所需的工具使用令牌数量如下所示（不包括上面列出的额外令牌）：

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

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

​

下一步

在我们的 cookbook 中探索现成的工具使用代码示例：