使用 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": "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"]
  }
}

​

工具使用系統提示

當您使用 tools 參數呼叫 Anthropic API 時，我們會根據工具定義、工具配置和任何用戶指定的系統提示構建一個特殊的系統提示。構建的提示旨在指導模型使用指定的工具並提供工具正常運作所需的必要上下文：

在這個環境中，您可以使用一組工具來回答用戶的問題。
{{ 格式說明 }}
字串和標量參數應按原樣指定，而列表和物件應使用 JSON 格式。請注意，字串值的空格不會被去除。輸出不需要是有效的 XML，而是使用正則表達式解析。
以下是 JSONSchema 格式的可用函數：
{{ JSON SCHEMA 中的工具定義 }}
{{ 用戶系統提示 }}
{{ 工具配置 }}

​

工具定義的最佳實踐

要在使用工具時獲得 Claude 的最佳表現，請遵循以下指導原則：

• 提供極其詳細的描述。 這是影響工具性能最重要的因素。您的描述應該解釋工具的每個細節，包括：
  • 工具的功能
  • 何時應該使用（以及何時不應該使用）
  • 每個參數的含義及其如何影響工具的行為
  • 任何重要的注意事項或限制，例如如果工具名稱不清楚，工具不會返回哪些信息。您能為 Claude 提供的工具相關上下文越多，它就越能更好地決定何時以及如何使用它們。每個工具描述至少應有 3-4 個句子，如果工具複雜，則需要更多。
• 優先考慮描述而非示例。 雖然您可以在工具的描述或隨附的提示中包含如何使用工具的示例，但這比完整清晰地解釋工具的目的和參數不太重要。只有在您完全充實了描述之後才添加示例。

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "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 時區（涵蓋舊金山，加州）的當前時間。</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 類型為 auto 時，設置 disable_parallel_tool_use=true，確保 Claude 最多使用一個工具
• 當 tool_choice 類型為 any 或 tool 時，設置 disable_parallel_tool_use=true，確保 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，這很可能是舊金山，加州。</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，這很可能是舊金山，加州。</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"}
}

​

定價

Tool use requests are priced based on:

1. The total number of input tokens sent to the model (including in the tools parameter)
2. The number of output tokens generated
3. 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.

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

請參考我們的模型概述表以了解當前每個模型的價格。

當您發送工具使用提示時，就像任何其他 API 請求一樣，回應將輸出輸入和輸出令牌計數作為報告的 usage 指標的一部分。

​

下一步

探索我們的 cookbook 中現成可實施的工具使用代碼示例：