工具使用的運作方式

本頁說明工具使用背後的概念：工具在何處執行、代理迴圈如何運作，以及何時工具使用是正確的方法。如需實作指引，請從教學或實作指南開始。



工具使用契約

工具使用是您的應用程式與模型之間的契約。您指定可用的操作及其輸入和輸出的形式；Claude 決定何時以及如何呼叫它們。模型本身從不執行任何東西。它發出結構化的請求，您的程式碼（或 Anthropic 的伺服器）執行該操作，然後結果回流到對話中。

這個契約使模型的行為不再像文字生成器，而更像是您呼叫的函式。具有傳統 API 經驗的工程師可以像整合任何其他型別化介面一樣整合工具使用：定義結構描述、處理回呼、回傳結果。不同之處在於，另一端的呼叫者是一個語言模型，它根據對話內容選擇要調用哪個函式。



工具在何處執行

工具之間的主要區別軸是程式碼在何處執行。每個工具都屬於三個類別之一，而該類別決定了您的應用程式需要負責什麼。



使用者定義的工具（用戶端執行）

您撰寫結構描述、您執行程式碼、您回傳結果。這是主要的使用情境：絕大多數的工具使用流量都是使用者定義的工具呼叫應用程式特定的邏輯。

當 Claude 決定使用您的其中一個工具時，API 回應會包含一個 tool_use 區塊，其中有工具名稱和一個包含引數的 JSON 物件。您的應用程式提取這些引數、執行操作（資料庫查詢、HTTP 呼叫、檔案寫入，或該工具所做的任何事情），並在下一個請求中以 tool_result 區塊將輸出傳回。Claude 從不會看到您的實作；它只會看到您提供的結構描述和您回傳的結果。



Anthropic 結構描述工具（用戶端執行）

對於少數常見操作（管理暫存記憶體、執行 shell 命令、編輯檔案、控制瀏覽器），Anthropic 發布工具結構描述，而您的應用程式負責執行。此類別中的工具包括 memory、bash、text_editor 和 computer。

執行模型與使用者定義的工具完全相同：回應包含一個 tool_use 區塊，您的程式碼執行操作，然後您傳回一個 tool_result。使用 Anthropic 結構描述工具而非自行定義等效工具的原因是，這些結構描述已經過訓練。Claude 已在數千個使用這些確切工具簽章的成功軌跡上進行最佳化，因此與執行相同功能的自訂工具相比，它呼叫這些工具更可靠，並且能更優雅地從錯誤中恢復。該結構描述正是模型已經預期的介面。



伺服器執行的工具

對於 web_search、web_fetch、code_execution 和 tool_search，Anthropic 負責執行程式碼。您在請求中啟用該工具，伺服器會處理其餘所有事情。您永遠不需要為這些工具建構 tool_result 區塊。當一個回合只呼叫伺服器工具時，伺服器端迴圈會在回應到達您之前執行操作並將輸出回饋給模型，除非迴圈在完成前停止，最常見的情況是暫停。

您收到的回應包含 server_tool_use 區塊，顯示執行了什麼以及回傳了什麼。在一般情況下，當您看到它們時執行已經完成，您的應用程式的工作是啟用工具並讀取最終答案，而不是參與執行迴圈；主要的例外情況是暫停的迴圈（pause_turn）以及同時呼叫用戶端工具的回合。



代理迴圈（用戶端工具）

用戶端執行的工具（包括使用者定義的和 Anthropic 結構描述的）需要您的應用程式驅動一個迴圈。模型無法執行您的程式碼，因此每次工具呼叫都是一次往返：模型提出請求、您執行、您回報結果、模型繼續。

標準形式是一個以 stop_reason 為鍵的 while 迴圈：

1. 傳送包含您的 tools 陣列和使用者訊息的請求。
2. Claude 以 stop_reason: "tool_use" 和一個或多個 tool_use 區塊回應。
3. 執行每個工具。將輸出格式化為 tool_result 區塊。
4. 傳送一個新請求，其中包含原始訊息、助理的回應，以及一個包含 tool_result 區塊的使用者訊息。
5. 當 stop_reason 為 "tool_use" 時，從步驟 2 重複。

實際上，這可以理解為：當 stop_reason == "tool_use" 時，執行工具並繼續對話。迴圈在任何其他停止原因（"end_turn"、"max_tokens"、"stop_sequence" 或 "refusal"）時退出，這表示 Claude 已產生最終答案，或因其他原因停止，而您的應用程式應處理該情況。

有關建構請求、處理平行工具呼叫和格式化結果的機制，請參閱處理工具呼叫。



伺服器端迴圈

伺服器執行的工具在 Anthropic 的基礎設施內執行自己的迴圈。來自您應用程式的單一請求可能會在回應返回之前觸發多次網路搜尋或程式碼執行。模型搜尋、讀取結果、決定再次搜尋，並反覆迭代直到獲得所需內容，整個過程都不需要您的應用程式參與。

這個內部迴圈有迭代次數限制。如果模型在達到上限時仍在迭代，回應會以 stop_reason: "pause_turn" 而非 "end_turn" 返回。暫停的回合表示工作尚未完成；重新傳送對話（包括暫停的回應）以讓模型從中斷處繼續。請參閱伺服器工具以了解繼續模式。

如果 Claude 在同一組平行工具呼叫中同時呼叫伺服器工具和用戶端工具，迴圈也會在伺服器工具執行之前將控制權交還給您。此時回應會以 stop_reason: "tool_use" 返回，並包含一個尚無結果區塊的 server_tool_use 區塊；API 會在您回傳用戶端工具結果後執行它。請參閱停止原因與後備處理以了解確切的契約。



何時使用工具（以及何時不該使用）

當任務需要模型無法僅從文字完成的事情時，工具使用就適用：

• 具有副作用的動作。 傳送電子郵件、寫入檔案、更新記錄。模型可以描述這些動作，但只有工具才能執行它們。
• 即時或外部資料。 目前價格、今日天氣、資料庫的內容。任何在訓練資料之外或特定於您系統的內容都需要工具來擷取。
• 結構化、保證形式的輸出。 當您需要具有特定欄位的 JSON 物件，而非恰好包含該資訊的純文字時，工具結構描述可強制執行該形式。
• 呼叫現有系統。 資料庫、內部 API、檔案系統。工具使用是自然語言請求與實現這些請求的系統之間的橋樑。

判斷您應該使用工具的跡象：如果您正在撰寫正規表示式以從模型輸出中提取決策，那麼該決策應該是一個工具呼叫。解析自由格式文字以恢復結構化意圖，表示該結構應該屬於結構描述。

工具使用不適用於以下情況：

• 模型可以僅從訓練資料回答。摘要、翻譯和一般知識問題不需要工具往返。
• 互動是一次性問答且沒有副作用。如果沒有東西需要執行，工具就無事可做。
• 工具呼叫的延遲會主導一個簡單的回應。每次工具呼叫至少是一次額外的往返；對於輕量級任務，開銷可能超過工作本身。



在不同方法之間選擇



後續步驟