使用Claude的工具功能

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

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

​

工具使用的工作原理

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

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

​

如何实现工具使用

​

选择模型

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

对于简单的工具,使用Claude 3.5 Haiku或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提供的关于工具的上下文越多,它就越能更好地决定何时以及如何使用它们。每个工具描述至少应该有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决定是否调用任何提供的工具。这是提供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 3 Opus模型会这样做,而Sonnet和Haiku可以被提示这样做。

例如,给定提示”旧金山现在的天气如何,那里现在几点了?“,Claude可能会回应:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>要回答这个问题,我将:1. 使用get_weather工具获取旧金山的当前天气。2. 使用get_time工具获取America/Los_Angeles时区(覆盖旧金山,CA)的当前时间。</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-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>我需要使用get_weather,用户想要SF,这很可能是San Francisco, CA。</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-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>我需要调用get_weather函数,用户想要SF,这很可能是San Francisco, CA。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-7-sonnet-20250219",
  "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时,我们还会自动包含一个特殊的系统提示,使模型能够使用工具。每个模型所需的工具使用令牌数列在下面(不包括上面列出的额外令牌)。请注意,该表假设至少提供了1个工具。如果没有提供tools,则none工具选择使用0个额外系统提示令牌。

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

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

​

下一步

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