Messages工具

工具使用的運作方式

Copy page



了解工具使用迴圈、工具在何處執行，以及何時應使用工具而非純文字敘述。

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

工具使用契約

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

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

工具在何處執行

工具之間最主要的差異軸線在於程式碼在何處執行。每個工具都屬於以下三類之一，而所屬類別決定了您的應用程式需要負責什麼。

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

您撰寫 schema、您執行程式碼、您回傳結果。這是最常見的情況：絕大多數的工具使用流量都是使用者定義的工具呼叫應用程式特定的邏輯。

當 Claude 呼叫您的某個工具時，API 回應會包含一個 tool_use 區塊，其中帶有工具名稱以及一個引數的 JSON 物件。您的應用程式擷取這些引數、執行操作（資料庫查詢、HTTP 呼叫、檔案寫入，或該工具所做的任何事），然後在下一個請求中以 tool_result 區塊將輸出送回。Claude 永遠看不到您的實作；它只看得到您提供的 schema 以及您回傳的結果。

Anthropic schema 工具（用戶端執行）

針對少數常見操作（管理暫存記憶、執行 shell 指令、編輯檔案、控制桌面或瀏覽器），Anthropic 會發布工具 schema，而由您的應用程式處理執行。此類別中的工具包括 memory、bash、text_editor、computer 以及 browser。

其執行模型與使用者定義的工具完全相同：回應包含一個 tool_use 區塊，您的程式碼執行操作，然後您送回一個 tool_result。之所以使用 Anthropic schema 工具而非自行定義等效工具，原因在於這些 schema 是經過訓練內建的。Claude 已針對數千條使用這些確切工具簽章的成功軌跡進行最佳化，因此相較於功能相同的自訂工具，它能更可靠地呼叫這些工具，並更從容地從錯誤中恢復。這個 schema 就是模型原本就預期的介面。

伺服器執行的工具

對於 web_search、web_fetch、code_execution 以及 tool_search，由 Anthropic 執行程式碼。您在請求中啟用該工具，其餘一切由伺服器處理。您永遠不需要為這些工具建構 tool_result 區塊。當某一輪只呼叫伺服器工具時，伺服器端迴圈會執行操作，並在回應送達您之前將輸出回饋給模型，除非迴圈在完成前停止，最常見的原因是它暫停了。

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

代理迴圈（用戶端工具）

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

其標準形式是一個以 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 物件，而非恰好包含該資訊的文字敘述時，工具 schema 能強制確保其形式。
• 呼叫既有系統。 資料庫、內部 API、檔案系統。工具使用是自然語言請求與實現這些請求的系統之間的橋樑。

一個您應該使用工具的明確徵兆：如果您正在撰寫正規表示式來從模型輸出中擷取某個決策，那麼該決策本應是一次工具呼叫。解析自由格式文字以還原結構化意圖，正表示該結構應該屬於 schema。

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

• 模型僅憑訓練即可回答。摘要、翻譯以及一般知識問題不需要工具往返。
• 互動是沒有副作用的單次問答。如果沒有東西需要執行，工具就無事可做。
• 工具呼叫的延遲會主導一個微不足道的回應。每次工具呼叫至少是一次額外的往返；對於輕量任務而言，其額外負擔可能超過工作本身。

在各種做法之間選擇

後續步驟