Claude Platform Docs
Messages工具

處理工具呼叫

解析 tool_use 區塊、格式化 tool_result 回應,並使用 is_error 處理錯誤。

當 Claude 的回應包含 tool_use 區塊時,您的程式碼會執行每個工具,並傳回 tool_result 區塊,其中也包括任何錯誤。當您需要對工具執行進行自訂控制時,請自行撰寫此程式碼。否則,請使用 SDK 的工具執行器,它會為您執行工具並傳送結果。

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

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

回應的 stop_reason 為 tool_use,並包含一個或多個 tool_use 內容區塊,其中包括:

  • id:此特定工具使用區塊的唯一識別碼。稍後會用它來對應工具結果。
  • name:所使用工具的名稱。
  • input:一個物件,包含傳遞給工具的輸入,符合該工具的 input_schema。

屬於電腦使用或瀏覽器使用工具集成員的 tool_use 區塊還會帶有 toolset_name 欄位("computer" 或 "browser")。其 name 是 Claude 正在呼叫的成員工具,例如 screenshot 或 navigate,因此請同時依據這兩個欄位來分派這些區塊。

當您收到用戶端工具的工具使用回應時,請依照以下步驟操作:

  1. 針對每個 tool_use 區塊,執行該區塊所指定的工具,並傳入其 input。
  2. 在新的請求中,保留先前的訊息,並將回應的 content 原封不動地新增為 assistant 訊息。
  3. 新增一則 user 訊息,針對該內容中的每個 tool_use 區塊各包含一個 tool_result 區塊,即使工具執行失敗也一樣。
  4. 使用與第一個請求相同的 tools 傳送請求。Claude 會使用工具結果來繼續其回應。
  5. 如果下一個回應的 stop_reason 也是 tool_use,請重複這些步驟。若為其他值,請參閱停止原因快速參考。

若要查看以完整程式實作這些步驟的範例,請參閱教學:建構一個使用工具的代理。

每個 tool_result 區塊的 type 皆設為 tool_result,並包含以下欄位:

  • tool_use_id:此結果所回應之 tool_use 區塊的 id。
  • content(選填):工具的結果,可以是字串或內容區塊的列表。這些內容區塊可以使用 text、image、document 或 search_result 類型。
  • is_error(選填):若工具執行失敗或呼叫無效,請設為 true。

例如,成功的工具結果如下所示:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "15 degrees"
    }
  ]
}

回應電腦使用或瀏覽器使用成員區塊的 tool_result 也必須回傳與 tool_use 區塊相同的 toolset_name 值;省略該值的成員結果會被拒絕。其 content 的範圍也較窄:成員結果只能包含 text 和 image 區塊,而瀏覽器使用結果可以額外加入一個 browser_state 區塊(分頁管理成員僅回傳該區塊)。

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

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

使用 is_error 處理錯誤

當用戶端工具執行失敗或呼叫無效時,請傳送 is_error 設為 true 的 tool_result 區塊。Claude 隨後可能會以新的 tool_use 區塊再次呼叫該工具,因此請限制您的迴圈允許的重試次數。

後續步驟

處理 Claude 在單一回合中呼叫多個工具的回應。

讓 SDK 為您管理 tool_use 迴圈、結果格式化與重試。

撰寫能引導 Claude 選用正確工具的結構描述與說明。

這個頁面有幫助嗎?