處理工具呼叫
解析 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,因此請同時依據這兩個欄位來分派這些區塊。
{
"id": "msg_01Aq9w938a90dw8q",
"model": "claude-opus-5-5",
"stop_reason": "tool_use",
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll check the current weather in San Francisco for you."
},
{
"type": "tool_use",
"id": "toolu_01A09q90qw90lq917835lq9",
"name": "get_weather",
"input": { "location": "San Francisco, CA", "unit": "celsius" }
}
]
}當您收到用戶端工具的工具使用回應時,請依照以下步驟操作:
- 針對每個
tool_use區塊,執行該區塊所指定的工具,並傳入其input。 - 在新的請求中,保留先前的訊息,並將回應的
content原封不動地新增為assistant訊息。 - 新增一則
user訊息,針對該內容中的每個tool_use區塊各包含一個tool_result區塊,即使工具執行失敗也一樣。 - 使用與第一個請求相同的
tools傳送請求。Claude 會使用工具結果來繼續其回應。 - 如果下一個回應的
stop_reason也是tool_use,請重複這些步驟。若為其他值,請參閱停止原因快速參考。
若要查看以完整程式實作這些步驟的範例,請參閱教學:建構一個使用工具的代理。
每個 tool_result 區塊的 type 皆設為 tool_result,並包含以下欄位:
tool_use_id:此結果所回應之tool_use區塊的id。content(選填):工具的結果,可以是字串或內容區塊的列表。這些內容區塊可以使用text、image、document或search_result類型。is_error(選填):若工具執行失敗或呼叫無效,請設為true。
例如,成功的工具結果如下所示:
{
"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 區塊(分頁管理成員僅回傳該區塊)。
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "15 degrees" },
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
}
]
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9"
}
]
}{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": [
{ "type": "text", "text": "The weather is" },
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "15 degrees"
}
}
]
}
]
}例如,這會導致 400 錯誤:
{
"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 會在內部執行工具,並將結果直接整合到其回應中,無需額外的使用者互動。
使用 is_error 處理錯誤
當用戶端工具執行失敗或呼叫無效時,請傳送 is_error 設為 true 的 tool_result 區塊。Claude 隨後可能會以新的 tool_use 區塊再次呼叫該工具,因此請限制您的迴圈允許的重試次數。
如果工具本身在執行期間拋出錯誤(例如,擷取天氣資料時發生網路錯誤),您可以在 content 中回傳錯誤訊息,並附上 "is_error": true:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "ConnectionError: the weather service API is not available (HTTP 500)",
"is_error": true
}
]
}Claude 隨後可以再次呼叫該工具,或告訴使用者發生了什麼事。例如,Claude 可能會說:「很抱歉,由於天氣服務 API 無法使用,我無法取得目前的天氣。請稍後再試。」
如果 Claude 嘗試使用工具的方式無效(例如缺少必要參數),這通常表示 Claude 沒有足夠的資訊來正確使用該工具。開發期間最好的做法是在您的工具定義中使用更詳細的 description 值,然後再次嘗試請求。
不過,您也可以使用指出錯誤的 tool_result 繼續對話:
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}Claude 隨後可以在補上缺少的資訊後再次呼叫該工具。
與用戶端工具不同,您不需要為伺服器工具傳送 is_error 結果。當伺服器工具遇到錯誤時(例如網頁搜尋期間的網路問題),API 會在該工具的結果區塊中回傳錯誤。在大多數情況下,Claude 隨後會改用其他方法繼續,或向使用者提供說明。
關於網頁搜尋的錯誤代碼,請參閱網頁搜尋工具錯誤。
後續步驟
處理 Claude 在單一回合中呼叫多個工具的回應。
讓 SDK 為您管理 tool_use 迴圈、結果格式化與重試。
撰寫能引導 Claude 選用正確工具的結構描述與說明。
這個頁面有幫助嗎?