處理工具呼叫

本頁涵蓋工具呼叫生命週期：從 Claude 的回應中讀取 tool_use 區塊、在您的回覆中格式化 tool_result 區塊，以及發出錯誤信號。如需自動處理此操作的 SDK 抽象，請參閱 Tool Runner。

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

處理用戶端工具的結果

回應將具有 tool_use 的 stop_reason 和一個或多個 tool_use 內容區塊，其中包括：

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

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

1. 從 tool_use 區塊中提取 name、id 和 input。
2. 在您的程式碼庫中執行與該工具名稱對應的實際工具，傳入工具 input。
3. 透過發送新訊息來繼續對話，其 role 為 user，content 區塊包含 tool_result 類型和以下資訊：
   • 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 類型。
   • is_error（選用）：如果工具執行導致錯誤，請設定為 true。

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ 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?" } // ✅ tool_result 之後的文字
  ]
}

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

處理伺服器工具的結果

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

使用 is_error 處理錯誤

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

後續步驟

• 如需在一次轉換中執行多個工具，請參閱 Parallel tool use。
• 如需自動執行此迴圈的 SDK 抽象，請參閱 Tool Runner。
• 如需完整的工具使用工作流程，請參閱 Define tools。