工具使用（函數呼叫）

Claude 能夠與外部客戶端工具和函數互動，讓您可以為 Claude 配備自己的自定義工具來執行更多樣化的任務。

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

​

工具使用的運作方式

透過以下步驟將外部工具與 Claude 整合：

注意：步驟 3 和 4 是可選的。對於某些工作流程，Claude 的工具使用請求（步驟 2）可能就足夠了，無需將結果發送回 Claude。

​

如何實現工具使用

​

選擇模型

通常，對於複雜的工具和模糊的查詢，使用 Claude 3.5 Sonnet 或 Claude 3 Opus；它們能更好地處理多個工具並在需要時尋求澄清。

對於簡單的工具，使用 Claude 3.5 Haiku 或 Claude 3 Haiku，但請注意它們可能會推斷缺失的參數。

​

指定工具

工具在 API 請求的頂層 tools 參數中指定。每個工具定義包括：

{
  "name": "get_weather",
  "description": "獲取指定位置的當前天氣",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "城市和州，例如 San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "溫度單位，可以是 'celsius' 或 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

​

工具使用系統提示

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

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

​

工具定義的最佳實踐

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

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

{
  "name": "get_stock_price",
  "description": "檢索給定股票代碼的當前股價。股票代碼必須是在紐約證券交易所或納斯達克等主要美國證券交易所上市的公開交易公司的有效代碼。該工具將返回最新的交易價格（以美元計）。當用戶詢問特定股票的當前或最近價格時應使用它。它不會提供有關股票或公司的任何其他信息。",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "股票代碼，例如 AAPL 代表蘋果公司"
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "獲取股票代碼的股價。",
  "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 訊息中添加明確的指示。例如：倫敦的天氣如何？在您的回應中使用 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 字段中設置 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-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>我需要使用 get_weather，用戶想要 SF，這很可能是 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 度"）或嵌套內容區塊的列表（例如 "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-5-sonnet-20241022",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>我需要呼叫 get_weather 函數，用戶想要 SF，這很可能是 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-5-sonnet-20241022",
  "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"}
}

​

定價

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

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

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

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

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

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

​

下一步

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