ClaudeAI-API函数调用[工具调用]使用教程

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

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

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

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    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's the weather like in San Francisco?"}],
)
print(response)

工具的使用方式

按照以下步骤将外部工具与 Claude 集成：

1 向Claude提供工具和用户提示

• 在 API 请求中使用名称、描述和输入模式定义工具。
• 包括可能需要这些工具的用户提示，例如“旧金山的天气怎么样？”

2 Claude决定使用工具

• Claude评估是否有任何工具可以帮助用户的查询。
• 如果是，Claude 会构建一个格式正确的工具使用请求。
• API 响应有一个stop_reason，tool_use表明 Claude 的意图。

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

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

4 Claude 使用工具结果来制定响应

• Claude分析工具结果以制定对原始用户提示的最终响应。

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

所有工具均由用户提供

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

​如何实现工具的使用

​选择模型

一般来说，对于复杂的工具和模糊的查询使用 Claude 3 Opus；它可以更好地处理多种工具并在需要时寻求澄清。

使用 Haiku 作为简单的工具，但请注意它可能会推断出缺失的参数。

​指定工具

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

简单工具定义示例

​工具定义的最佳实践

为了在使用工具时发挥 Claude 的最佳性能，请遵循以下准则：

• 提供极其详细的描述。这是迄今为止工具性能最重要的因素。您的描述应该解释有关该工具的每个细节，包括：
  • 该工具的作用
  • 何时应该使用（何时不应该使用）
  • 每个参数的含义以及它们如何影响工具的行为
  • 任何重要的注意事项或限制，例如如果工具名称不清楚，该工具不会返回哪些信息。您能向 Claude 提供的有关您的工具的背景信息越多，它就越能决定何时以及如何使用它们。每个工具描述至少要有 3-4 句话，如果工具很复杂，则要多写一些。
• 描述优先于示例。虽然您可以在工具描述或随附提示中包含如何使用工具的示例，但这不如对工具的用途和参数进行清晰全面的解释重要。仅在充分阐述描述后再添加示例。

良好工具描述的示例

工具描述不佳示例

好的描述清楚地解释了该工具的作用、何时使用、返回的数据以及参数的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，我们将预填充助手消息以强制使用工具。这意味着模型不会在内容块之前发出思路链text内容块tool_use，即使明确要求这样做。

我们的测试表明，这不会降低性能。如果您想保持思路（尤其是使用 Opus）同时仍要求模型使用特定工具，则可以使用{"type": "auto"}for tool_choice（默认）并在user消息中添加明确说明。例如：What's the weather like in London? Use the get_weather tool in your response.

​JSON 输出

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

​思路

在使用工具时，Claude 通常会展示其“思路链”，即它用来分解问题并决定使用哪些工具的逐步推理。如果tool_choice设置为， Claude 3 Opus 模型将执行此操作auto（这是默认值，请参阅强制使用工具），并且可以提示 Sonnet 和 Haiku 执行此操作。

例如，当提示“旧金山现在的天气怎么样，那里几点了？”时，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 3 Sonnet 模型中，思路链默认不太常见，但您可以通过"Before answering, explain your reasoning step-by-step in tags."在用户消息或系统提示中添加类似内容来提示 Claude 展示其推理。

需要注意的是，虽然<thinking>标签是 Claude 用来表示思路链的常见惯例，但确切的格式（例如此 XML 标签的名称）可能会随时间而变化。您的代码应该将思路链视为任何其他助手生成的文本，而不是依赖于标签的存在或特定格式<thinking>。

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

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

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

带有“tool_use”内容块的示例 API 响应

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

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

成功工具结果示例

带图像的工具结果示例

空工具结果示例

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

与其他 API 的区别

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

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

​排除错误

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

工具执行错误

已超出最大令牌数

工具名称无效

<search_quality_reflection> 标签

​工具使用示例

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

单一工具示例

多工具示例

缺失信息

顺序工具

思路链工具的使用

JSON 模式

​价格

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

使用工具获得的额外代币来自：

• API 请求中的参数tools（工具名称、描述和架构）
• tool_useAPI 请求和响应中的内容块
• tool_resultAPI 请求中的内容块

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

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

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