工具使用(函数调用)

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

通过我们新的综合工具使用课程学习使用Claude掌握工具使用所需的一切知识!请继续使用此表单分享您的想法和建议。

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

工具使用的工作原理

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

为Claude提供工具和用户提示

在API请求中定义具有名称、描述和输入模式的工具。
包含可能需要这些工具的用户提示,例如”旧金山的天气如何?”

Claude决定使用工具

Claude评估是否有任何工具可以帮助回答用户的查询。
如果是,Claude构造一个格式正确的工具使用请求。
API响应的stop_reason为tool_use,表示Claude的意图。

提取工具输入、运行代码并返回结果

在您的端,从Claude的请求中提取工具名称和输入。
在客户端执行实际的工具代码。
继续对话,发送一个包含tool_result内容块的新user消息。

Claude使用工具结果制定响应

Claude分析工具结果,为原始用户提示制定最终响应。

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

所有工具都由用户提供

需要注意的是,Claude没有访问任何内置的服务器端工具。所有工具都必须由您(用户)在每个API请求中明确提供。这使您可以完全控制和灵活地决定Claude可以使用的工具。

如何实现工具使用

选择模型

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

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

指定工具

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

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

JSON

{
  "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"]
  }
}

这个名为get_weather的工具需要一个输入对象,其中包含一个必需的location字符串和一个可选的unit字符串,后者必须是”celsius”或”fahrenheit”。

工具定义的最佳实践

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

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

JSON

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

JSON

{
  "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可能会回应:

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 3 Sonnet模型,链式思考默认不太常见,但您可以通过在用户消息或系统提示中添加类似”在回答之前,请用标签解释您的逐步推理。“来提示Claude展示其推理。

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

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

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

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

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "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"}
    }
  ]
}

当您收到工具使用响应时,您应该:

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

JSON

{
  "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...",
          }
        }
      ]
    }
  ]
}

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

与其他API的区别

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

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

故障排除错误

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

如果工具本身在执行过程中抛出错误(例如,在获取天气数据时出现网络错误),您可以在content中返回错误消息,并设置"is_error": true:

JSON

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

然后Claude会将这个错误纳入其对用户的响应中,例如”很抱歉,我无法获取当前天气,因为天气服务API不可用。请稍后再试。”

如果Claude尝试使用的工具无效(例如缺少必需的参数),这通常意味着Claude没有足够的信息来正确使用该工具。在开发过程中,最好的办法是尝试在工具定义中使用更详细的description值重新发送请求。

然而,您也可以继续对话,发送一个指示错误的tool_result,Claude将尝试再次使用该工具,并填写缺失的信息:

JSON

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

如果工具请求无效或缺少参数,Claude会尝试2-3次进行更正,然后向用户道歉。

工具使用示例

以下是一些演示各种工具使用模式和技术的代码示例。为简洁起见,这些工具是简单的工具,工具描述比理想情况下确保最佳性能所需的要短。

Claude将返回类似以下的响应:

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-3-5-sonnet-20240620",
  "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"}
    }
  ]
}

然后您需要使用提供的输入执行get_weather函数,并在新的user消息中返回结果:

这将打印Claude的最终响应,其中包含天气数据:

JSON

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

如果用户的提示不包含足够的信息来填写工具的所有必需参数,Claude 3 Opus更有可能认识到缺少参数并询问。Claude 3 Sonnet可能会询问,特别是在被提示在输出工具请求之前思考时。但它也可能会尽力推断一个合理的值。

例如,使用上面的get_weather工具,如果您问Claude”天气如何?”而没有指定位置,Claude,特别是Claude 3 Sonnet,可能会对工具输入进行猜测:

JSON

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

这种行为并不能保证,特别是对于更模糊的提示和不如Claude 3 Opus智能的模型。如果Claude 3 Opus没有足够的上下文来填写必需的参数,它更有可能以澄清问题作为回应,而不是进行工具调用。

某些任务可能需要按顺序调用多个工具,使用一个工具的输出作为另一个工具的输入。在这种情况下,Claude将一次调用一个工具。如果被提示一次调用所有工具,Claude可能会猜测下游工具的参数,如果它们依赖于上游工具的结果。

以下是使用get_location工具获取用户位置,然后将该位置传递给get_weather工具的示例:

在这种情况下,Claude会首先调用get_location工具来获取用户的位置。在您在tool_result中返回位置后,Claude会使用该位置调用get_weather以获得最终答案。

完整的对话可能如下所示:

角色	内容
用户	我所在地的天气如何?
助手	<thinking>要回答这个问题,我首先需要使用get_location工具确定用户的位置。然后我可以将该位置传递给get_weather工具以找到那里的当前天气。</thinking>[get_location的工具使用]
用户	[get_location的工具结果,带有匹配的id和结果San Francisco, CA]
助手	[get_weather的工具使用,输入如下]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
用户	[get_weather的工具结果,带有匹配的id和结果”59°F (15°C), 多云”]
助手	根据您当前在旧金山的位置,现在的天气是59°F (15°C),多云。这是一个相当凉爽和阴天的日子。如果您要外出,可能需要带一件轻便的夹克。

这个例子展示了Claude如何将多个工具调用链接在一起,以回答需要从不同来源收集数据的问题。关键步骤是:

Claude首先意识到需要用户的位置来回答天气问题,所以它调用get_location工具。
用户(即客户端代码)执行实际的get_location函数,并在tool_result块中返回结果”San Francisco, CA”。
现在知道了位置,Claude继续调用get_weather工具,将”San Francisco, CA”作为location参数传入(以及一个猜测的unit参数,因为unit不是必需参数)。
用户再次使用提供的参数执行实际的get_weather函数,并在另一个tool_result块中返回天气数据。
最后,Claude将天气数据整合到对原始问题的自然语言回答中。

定价

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

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

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

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

模型	工具选择	工具使用系统提示令牌数
Claude 3.5 Sonnet	`auto` `any`, `tool`	294 tokens 261 tokens
Claude 3 Opus	`auto` `any`, `tool`	530 tokens 281 tokens
Claude 3 Sonnet	`auto` `any`, `tool`	159 tokens 235 tokens
Claude 3 Haiku	`auto` `any`, `tool`	264 tokens 340 tokens

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

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

下一步

探索我们的cookbooks中现成可实施的工具使用代码示例库:

计算器工具

学习如何将简单的计算器工具与Claude集成,以进行精确的数值计算。

客户服务代理

构建一个响应式客户服务机器人,利用客户端工具增强支持。

JSON提取器

了解Claude和工具使用如何从非结构化文本中提取结构化数据。

开始使用

了解 Claude

使用 Claude 构建

测试和评估

资源

工具使用(函数调用)

工具使用的工作原理

如何实现工具使用

选择模型

指定工具

工具定义的最佳实践

控制Claude的输出

强制使用工具

JSON输出

链式思考

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

故障排除错误

工具使用示例

定价

下一步

计算器工具

客户服务代理

JSON提取器

开始使用

了解 Claude

使用 Claude 构建

测试和评估

资源

​工具使用的工作原理

​如何实现工具使用

​选择模型

​指定工具

​工具定义的最佳实践

​控制Claude的输出

​强制使用工具

​JSON输出

​链式思考

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

​故障排除错误

​工具使用示例

​定价

​下一步

计算器工具

客户服务代理

JSON提取器

工具使用的工作原理

如何实现工具使用

选择模型

指定工具

工具定义的最佳实践

控制Claude的输出

强制使用工具

JSON输出

链式思考

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

故障排除错误

工具使用示例

定价

下一步