使用 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 時，我們會根據工具定義、工具配置和任何用戶指定的系統提示構建一個特殊的系統提示。構建的提示旨在指導模型使用指定的工具並提供工具正常運作所需的必要上下文：

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

​

工具定義的最佳實踐

要在使用工具時獲得最佳性能，請遵循以下準則：

• 提供極其詳細的描述。 這是影響工具性能最重要的因素。您的描述應該解釋工具的每個細節，包括：
  • 工具的功能
  • 何時應該使用（以及何時不應該使用）
  • 每個參數的含義及其如何影響工具的行為
  • 任何重要的注意事項或限制，例如如果工具名稱不清楚，工具不會返回哪些信息。您能為 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 決定是否調用任何提供的工具。這是默認值。
• any 告訴 Claude 它必須使用提供的工具之一，但不強制使用特定工具。
• tool 允許我們強制 Claude 始終使用特定工具。

此圖說明了每個選項的工作方式：

請注意，當您將 tool_choice 設置為 any 或 tool 時，我們會預填助手消息以強制使用工具。這意味著即使明確要求，模型也不會在 tool_use 內容區塊之前發出鏈式思考 text 內容區塊。

我們的測試表明，這不應該降低性能。如果您想在請求模型使用特定工具的同時保持鏈式思考（特別是使用 Opus），您可以將 tool_choice 設置為 {"type": "auto"} （默認值），並在 user 消息中添加明確的指示。例如：What's the weather like in London? Use the get_weather tool in your response.

​

JSON 輸出

工具不一定需要是客戶端函數 — 只要您希望模型返回符合提供架構的 JSON 輸出，就可以使用工具。例如，您可以使用具有特定架構的 record_summary 工具。請參閱工具使用示例以獲取完整的工作示例。

​

思維鏈

在使用工具時，Claude 通常會顯示其「思維鏈」，即它用來分解問題並決定使用哪些工具的逐步推理。如果 tool_choice 設置為 auto（這是默認值，請參閱強制使用工具），Claude 3 Opus 模型會這樣做，而 Sonnet 和 Haiku 可以通過提示來實現這一點。

例如，給定提示「What’s the weather like in San Francisco right now, and what time is it there?」，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 的推理過程，並可以幫助您調試意外行為。

對於 Claude 3 Sonnet 模型，默認情況下思維鏈較少出現，但您可以通過在用戶消息或系統提示中添加類似「Before answering, explain your reasoning step-by-step in tags.」的內容來提示 Claude 顯示其推理過程。

重要的是要注意，雖然 <thinking> 標籤是 Claude 用來表示其思維鏈的常見約定，但確切的格式（例如這個 XML 標籤的名稱）可能會隨時間而改變。您的代碼應該將思維鏈視為任何其他助手生成的文本，而不應依賴 <thinking> 標籤的存在或特定格式。

​

禁用並行工具使用

默認情況下，Claude 可能會使用多個工具來回答用戶查詢。您可以通過在 tool_choice 字段中設置 disable_parallel_tool_use=true 來禁用此行為。

• 當 tool_choice 類型為 auto 時，這確保 Claude 最多使用一個工具
• 當 tool_choice 類型為 any 或 tool 時，這確保 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>I need to use the 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"}
    }
  ]
}

當您收到工具使用回應時，您應該：

1. 從 tool_use 區塊中提取 name、id 和 input。
2. 在您的代碼庫中運行與該工具名稱對應的實際工具，傳入工具 input。
3. 通過發送一個 role 為 user 的新消息繼續對話，該消息包含具有以下信息的 tool_result 類型的 content 區塊：
   • tool_use_id：這是結果對應的工具使用請求的 id。
   • content：工具的結果，可以是字串（例如 "content": "15 degrees"）或嵌套內容區塊的列表（例如 "content": [{"type": "text", "text": "15 degrees"}]）。這些內容區塊可以使用 text 或 image 類型。
   • is_error（可選）：如果工具執行導致錯誤，則設置為 true。

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrees"},
        {
          "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: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

​

工具使用示例

以下是展示各種工具使用模式和技術的幾個代碼示例。為了簡潔起見，這些工具都是簡單的工具，工具描述也比確保最佳性能所需的要短。

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

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

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

​

定價

工具使用請求的定價與任何其他 Claude API 請求相同，基於發送給模型的輸入令牌總數（包括 tools 參數中的令牌）和生成的輸出令牌數。

工具使用帶來的額外令牌來自：

• API 請求中的 tools 參數（工具名稱、描述和架構）
• API 請求和回應中的 tool_use 內容區塊
• API 請求中的 tool_result 內容區塊

當您使用 tools 時，我們還會自動包含一個特殊的系統提示，使模型能夠使用工具。每個模型所需的工具使用令牌數量列在下面（不包括上面列出的額外令牌）：

這些令牌數量會加到您的正常輸入和輸出令牌中，以計算請求的總成本。請參考我們的模型概述表以了解當前每個模型的價格。

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

​

下一步

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