Claude 工具使用

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-opus-4-20250514",
    "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 支持两种类型的工具：

客户端工具：在您的系统上执行的工具，包括：
- 用户定义的自定义工具，由您创建和实现
- Anthropic 定义的工具，如计算机使用（测试版）和文本编辑器，需要客户端实现
服务器工具：在 Anthropic 服务器上执行的工具，如网络搜索工具。这些工具必须在 API 请求中指定，但不需要您自己实现。

Anthropic 定义的工具使用版本化类型（例如，web_search_20250305，text_editor_20250124）以确保跨模型版本的兼容性。

客户端工具

通过以下步骤将客户端工具与 Claude 集成：

向 Claude 提供工具和用户提示

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

Claude 决定使用工具

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

执行工具并返回结果

从 Claude 的请求中提取工具名称和输入
在您的系统上执行工具代码
在包含 tool_result 内容块的新 user 消息中返回结果

Claude 使用工具结果制定响应

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

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

服务器工具

服务器工具遵循不同的工作流程：

向 Claude 提供工具和用户提示

服务器工具，如网络搜索，有自己的参数。
包含可能需要这些工具的用户提示，例如，“搜索有关 AI 的最新新闻。”

Claude 执行服务器工具

Claude 评估服务器工具是否可以帮助解答用户的查询。
如果是，Claude 执行该工具，结果会自动纳入 Claude 的响应中。

Claude 使用服务器工具结果制定响应

Claude 分析服务器工具结果，为原始用户提示制作最终响应。
服务器工具执行不需要额外的用户交互。

工具使用示例

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

单一工具示例

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "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"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The unit of temperature, either \"celsius\" or \"fahrenheit\""
                }
            },
            "required": ["location"]
        }
    }],
    "messages": [{"role": "user", "content": "What is the weather like in San Francisco?"}]
}'

Claude 将返回类似于以下内容的响应：

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to call the get_weather function, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "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"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either \"celsius\" or \"fahrenheit\""
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather like in San Francisco?"
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "<thinking>I need to use get_weather, and the user wants SF, which is likely San Francisco, CA.</thinking>"
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01A09q90qw90lq917835lq9",
                    "name": "get_weather",
                    "input": {
                        "location": "San Francisco, CA",
                        "unit": "celsius"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 degrees"
                }
            ]
        }
    ]
}'

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

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-20250514",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

多工具示例

您可以在单个请求中向 Claude 提供多个工具供其选择。以下是同时包含 get_weather 和 get_time 工具的示例，以及询问两者的用户查询。

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "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"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given time zone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The IANA time zone name, e.g. America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "What is the weather like right now in New York? Also what time is it there?"
    }]
}'

在这种情况下，Claude 很可能会尝试一次使用一个工具 — 先使用 get_weather 然后使用 get_time — 以完全回答用户的问题。但是，它有时也会一次输出两个 tool_use 块，特别是当它们彼此不依赖时。您需要执行每个工具并在单个 user 消息中的单独 tool_result 块中返回它们的结果。

缺失信息

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

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

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

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

顺序工具

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

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Get the current user location based on their IP address. This tool has no parameters or arguments.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "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"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What is the weather like where I am?"
    }]
}'

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

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

角色	内容
用户	我所在的地方天气如何？
助手	<thinking>要回答这个问题，我首先需要使用 get_location 工具确定用户的位置。然后我可以将该位置传递给 get_weather 工具，以找到那里的当前天气。</thinking>[使用 get_location 工具]
用户	[带有匹配 id 和结果 San Francisco, CA 的 get_location 工具结果]
助手	[使用 get_weather 工具，输入如下]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
用户	[带有匹配 id 和结果 “59°F (15°C), mostly cloudy” 的 get_weather 工具结果]
助手	根据您在旧金山的当前位置，现在的天气是 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 将天气数据整合到对原始问题的自然语言回答中。

思维链工具使用

JSON 模式

您可以使用工具让 Claude 生成遵循模式的 JSON 输出，即使您没有打算通过工具或函数运行该输出。

以这种方式使用工具时：

您通常希望提供单个工具
您应该设置 tool_choice（参见强制工具使用）以指示模型明确使用该工具
请记住，模型将把 input 传递给工具，所以工具的名称和描述应该从模型的角度出发。

以下使用 record_summary 工具按照特定格式描述图像。

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data \
'{
    "model": "claude-opus-4-20250514",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Record summary of an image using well-structured JSON.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "red value [0.0, 1.0]" },
"g": { "type": "number", "description": "green value [0.0, 1.0]" },
"b": { "type": "number", "description": "blue value [0.0, 1.0]" },
"name": { "type": "string", "description": "Human-readable color name in snake_case, e.g. \"olive_green\" or \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Key colors in the image. Limit to less than four."
                },
                "description": {
                    "type": "string",
                    "description": "Image description. One to two sentences max."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Estimated year that the image was taken, if it is a photo. Only set this if the image appears to be non-fictional. Rough estimates are okay!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Describe this image."}
        ]}
    ]
}'

定价

Tool use requests are priced based on:

The total number of input tokens sent to the model (including in the tools parameter)
The number of output tokens generated
For server-side tools, additional usage-based pricing (e.g., web search charges per search performed)

Client-side tools are priced the same as any other Claude API request, while server-side tools may incur additional charges based on their specific usage.

The additional tokens from tool use come from:

The tools parameter in API requests (tool names, descriptions, and schemas)
tool_use content blocks in API requests and responses
tool_result content blocks in API requests

When you use tools, we also automatically include a special system prompt for the model which enables tool use. The number of tool use tokens required for each model are listed below (excluding the additional tokens listed above). Note that the table assumes at least 1 tool is provided. If no tools are provided, then a tool choice of none uses 0 additional system prompt tokens.

Model	Tool choice	Tool use system prompt token count
Claude Opus 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 4	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.7	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (Oct)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3	`auto`, `none` `any`, `tool`	530 tokens 281 tokens
Claude Sonnet 3	`auto`, `none` `any`, `tool`	159 tokens 235 tokens
Claude Haiku 3	`auto`, `none` `any`, `tool`	264 tokens 340 tokens

These token counts are added to your normal input and output tokens to calculate the total cost of a request.

请参阅我们的模型概述表了解当前每个模型的价格。

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

下一步

在我们的 cookbook 中探索随时可以实现的工具使用代码示例：

计算器工具

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

客户服务代理

构建一个响应迅速的客户服务机器人，利用客户端工具增强支持。

JSON 提取器

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

第一步

模型和定价

探索功能

了解 Claude

测试与评估

法律中心

智能体组件

Claude 工具使用

工具使用的工作原理

客户端工具

服务器工具

工具使用示例

定价

下一步

计算器工具

客户服务代理

JSON 提取器

第一步

模型和定价

探索功能

了解 Claude

测试与评估

法律中心

智能体组件

​工具使用的工作原理

​客户端工具

​服务器工具

​工具使用示例

​定价

​下一步

计算器工具

客户服务代理

JSON 提取器

工具使用的工作原理

客户端工具

服务器工具

工具使用示例

定价

下一步