工具使用的運作方式

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

工具使用契約

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

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

工具在哪裡執行

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

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

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

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

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

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

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

伺服器執行工具

對於 web_search、web_fetch、code_execution 和 tool_search，Anthropic 執行程式碼。您在請求中啟用工具，伺服器處理其他所有事情。您永遠不需要為這些工具建構 tool_result 區塊，因為伺服器端循環會執行操作並在回應到達您之前將輸出回饋給模型。

您收到的回應包含 server_tool_use 區塊，顯示執行了什麼以及回傳了什麼，但當您看到它們時，執行已經完成。您的應用程式的工作是啟用工具並讀取最終答案，而不是參與執行循環。

代理循環（客戶端工具）

客戶端執行工具（包括使用者定義和 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" 返回。暫停的回合意味著工作尚未完成；重新發送對話（包括暫停的回應）以讓模型從中斷處繼續。請參閱伺服器工具了解繼續模式。

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

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

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

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

工具使用不適合的情況：

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

選擇方法

後續步驟