使用 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 的 get_location 工具結果，結果為 San Francisco, CA]
助手	[使用 get_weather 工具，輸入如下]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
用戶	[帶有匹配 id 的 get_weather 工具結果，結果為「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 將天氣數據納入對原始問題的自然語言回應中。

思維鏈工具使用

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 指標的一部分。

下一步

在我們的食譜中探索現成可實現的工具使用代碼示例：

計算器工具

了解如何將簡單的計算器工具與 Claude 集成，以進行精確的數值計算。

客戶服務代理

構建一個響應式客戶服務機器人，利用客戶端工具增強支持。

JSON 提取器

了解 Claude 和工具使用如何從非結構化文本中提取結構化數據。

初步步驟

模型與定價

探索功能

瞭解 Claude

測試和評估

法律中心

代理元件

使用 Claude 的工具

工具使用的工作原理

客戶端工具

服務器工具

工具使用示例

定價

下一步

計算器工具

客戶服務代理

JSON 提取器

初步步驟

模型與定價

探索功能

瞭解 Claude

測試和評估

法律中心

代理元件

​工具使用的工作原理

​客戶端工具

​服務器工具

​工具使用示例

​定價

​下一步

計算器工具

客戶服務代理

JSON 提取器

工具使用的工作原理

客戶端工具

服務器工具

工具使用示例

定價

下一步