工具使用如何運作

本頁面解釋工具使用背後的概念：工具在何處運行、代理迴圈如何運作，以及何時工具使用是正確的方法。如需實踐指導，請從教程或實現指南開始。

工具使用契約

工具使用是您的應用程式和模型之間的契約。您指定哪些操作可用以及其輸入和輸出的形狀；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、文件系統。工具使用是自然語言請求和履行它們的系統之間的橋樑。

您應該使用工具的跡象：如果您正在編寫正則表達式以從模型輸出中提取決策，該決策應該已經是工具調用。解析自由形式的文字以恢復結構化意圖是結構應該在架構中的跡象。

工具使用不適合：

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

在方法之間選擇

後續步驟