處理工具呼叫

本頁面涵蓋工具呼叫的生命週期：從 Claude 的回應中讀取 tool_use 區塊、在您的回覆中格式化 tool_result 區塊，以及傳遞錯誤訊號。如需自動處理這些流程的 SDK 抽象層，請參閱 Tool Runner。

Claude 的回應會根據其使用的是用戶端工具或伺服器工具而有所不同。



處理來自用戶端工具的結果

回應的 stop_reason 會是 tool_use，並包含一個或多個 tool_use 內容區塊，其中包括：

• id：此特定工具使用區塊的唯一識別碼。稍後將用於比對工具結果。
• name：正在使用的工具名稱。
• input：一個物件，包含傳遞給工具的輸入，符合該工具的 input_schema。

當您收到用戶端工具的工具使用回應時，您應該：

1. 從 tool_use 區塊中擷取 name、id 和 input。
2. 在您的程式碼庫中執行對應該工具名稱的實際工具，並傳入工具的 input。
3. 透過傳送一則 role 為 user 的新訊息來繼續對話，該訊息包含一個 tool_result 類型的 content 區塊，以及下列資訊：
   • tool_use_id：此結果所對應的工具使用請求的 id。
   • content（選用）：工具的結果，可以是字串（例如 "content": "15 degrees"）、巢狀內容區塊的清單（例如 "content": [{"type": "text", "text": "15 degrees"}]），或文件區塊的清單（例如 "content": [{"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}}]）。這些內容區塊可以使用 text、image、document 或 search_result 類型。
   • is_error（選用）：如果工具執行導致錯誤，則設為 true。

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

收到工具結果後，Claude 將使用該資訊繼續生成對原始使用者提示的回應。



處理來自伺服器工具的結果

Claude 會在內部執行工具，並將結果直接整合到其回應中，無需額外的使用者互動。



使用 is_error 處理錯誤

在搭配 Claude 使用工具時，可能會發生幾種不同類型的錯誤：



後續步驟