處理工具呼叫
解析 tool_use 區塊、格式化 tool_result 回應，並使用 is_error 處理錯誤。
本頁涵蓋工具呼叫的生命週期：從 Claude 的回應中讀取 tool_use 區塊、在您的回覆中格式化 tool_result 區塊，以及傳達錯誤訊號。若要了解自動處理這些工作的 SDK 抽象層，請參閱 Tool Runner。
Claude 的回應會依其使用的是用戶端工具或伺服器工具而有所不同。
處理來自用戶端工具的結果
回應的 stop_reason 會是 tool_use，並包含一個或多個 tool_use 內容區塊，其中包括：
id：此特定工具使用區塊的唯一識別碼。稍後將用於比對工具結果。name：所使用工具的名稱。input：一個物件，包含傳遞給工具的輸入，符合該工具的input_schema。
屬於 computer use 或 browser use 工具集成員的 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區塊中擷取name、id和input。 - 在您的程式碼庫中執行與該工具名稱對應的實際工具，並傳入工具的
input。 - 透過傳送一則
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或search_result類型。is_error（選填）：若工具執行導致錯誤，請設為true。
回應 computer use 或 browser use 成員區塊的 tool_result 也必須回傳與 tool_use 區塊相同的 toolset_name 值；省略該值的成員結果會被拒絕。其 content 的範圍也較窄：成員結果只能包含 text 和 image 區塊，而 browser use 結果可以額外加入一個 browser_state 區塊（分頁管理成員僅回傳該區塊）。
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "15 degrees"
}
]
}{
"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"
}
}
]
}
]
}收到工具結果後，Claude 會使用該資訊繼續針對原始使用者提示生成回應。
處理來自伺服器工具的結果
Claude 會在內部執行工具，並將結果直接整合到其回應中，無需額外的使用者互動。
使用 is_error 處理錯誤
搭配 Claude 使用工具時，可能會發生幾種不同類型的錯誤：
如果工具本身在執行期間拋出錯誤（例如，擷取天氣資料時發生網路錯誤），您可以在 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 隨後會將此錯誤整合到其對使用者的回應中。例如：「很抱歉，由於天氣服務 API 無法使用，我無法取得目前的天氣。請稍後再試。」
如果 Claude 嘗試使用工具的方式無效（例如，缺少必要參數），通常表示 Claude 沒有足夠的資訊來正確使用該工具。在開發期間，最好的做法是在工具定義中使用更詳細的 description 值，然後再次嘗試該請求。
不過，您也可以使用指出錯誤的 tool_result 繼續推進對話，Claude 會嘗試補上缺少的資訊後再次使用該工具：
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01A09q90qw90lq917835lq9",
"content": "Error: Missing required 'location' parameter",
"is_error": true
}
]
}如果工具請求無效或缺少參數，Claude 會在向使用者致歉之前重試 2 至 3 次並進行修正。
當伺服器工具遇到錯誤時（例如，Web Search 的網路問題），Claude 會透明地處理這些錯誤，並嘗試向使用者提供替代回應或說明。與用戶端工具不同，您不需要為伺服器工具處理 is_error 結果。
特別針對網頁搜尋，可能的錯誤代碼包括：
too_many_requests：超出速率限制invalid_input：無效的搜尋查詢參數max_uses_exceeded：超出網頁搜尋工具的最大使用次數query_too_long：查詢超出最大長度unavailable：發生內部錯誤
後續步驟
處理 Claude 在單一回合中呼叫多個工具的回應。
讓 SDK 為您管理 tool_use 迴圈、結果格式化與重試。
撰寫能引導 Claude 選用正確工具的結構描述與說明。
Was this page helpful?