Tool Runner（SDK）

「Tool runner」（工具執行器）會處理代理迴圈、錯誤封裝和型別安全，讓您無需自行處理。當您需要人工審核（human-in-the-loop）、自訂日誌記錄或條件式執行時，請改用手動迴圈。

Tool runner 會自動執行以下操作，而無需手動處理工具呼叫、工具結果和對話管理：

• 在 Claude 呼叫工具時執行工具
• 處理請求/回應週期
• 管理對話狀態
• 提供型別安全和驗證



基本用法

使用 SDK 輔助函式定義工具，然後使用 tool runner 執行它們。

根據 SDK 的工具簽章，工具會以字串或內容區塊（文字、圖片或文件區塊）的形式回傳結果，因此工具可以回傳多模態結果。回傳的字串會成為單一文字內容區塊。若要回傳結構化資料（例如 JSON 物件或數字），請先將其編碼為字串。



迭代 tool runner

Tool runner 是一個可迭代物件，會產出來自 Claude 的訊息。在每次迭代中，runner 會檢查 Claude 是否請求了工具使用。如果是，它會執行工具並自動將結果傳回給 Claude，然後產出 Claude 的下一則訊息以繼續您的迴圈。

您可以在任何迭代中使用 break 陳述式結束迴圈。Runner 會持續迴圈，直到 Claude 回傳不含工具使用的訊息，或達到您設定的 max_iterations 為止。

如果您不需要中間訊息，可以直接取得最終訊息：



進階用法

在迴圈內，您可以讀取每個回應訊息，並在下一次 API 呼叫之前修改 runner 的狀態。每次迭代遵循以下生命週期：

1. Runner 以其目前狀態向 Messages API 發送請求。
2. Runner 將回應訊息產出給您的迴圈主體。
3. 您的迴圈主體執行。您可以讀取訊息並選擇性地修改 runner 的狀態。
4. 當您的迴圈主體返回時，runner 會檢查您是否修改了其訊息歷史記錄。
   • 如果您未修改訊息歷史記錄： Runner 會將助理訊息附加到其狀態。如果訊息包含工具呼叫，runner 會執行它們並附加結果。如果沒有工具呼叫，迴圈結束。
   • 如果您修改了訊息歷史記錄： Runner 會跳過其自動附加步驟，並原封不動地使用您的狀態。請參閱接管訊息歷史記錄。



接管訊息歷史記錄

預設情況下，runner 會為您管理對話狀態：在每個回合之後，它會將助理訊息和任何工具結果附加到自己的訊息歷史記錄中。當您想要重試某個回合（捨棄回應並重新發送）、插入後續訊息或自行建構工具結果時，您可以接管訊息歷史記錄。

您可以透過在迴圈主體內修改 runner 的訊息來接管。確切的方法取決於 SDK。請參閱後續各語言的分頁。

當您接管某次迭代時，runner 不會附加該回合的助理訊息或工具結果。您需要負責保持對話的有效性：自行附加助理訊息和工具結果（如果您希望該回合被計入）、有條件地修改狀態以便在沒有工具呼叫時迴圈仍能結束，並傳遞 max_iterations 以限制迴圈次數。所有七個 SDK 都支援 max_iterations。



自動上下文管理

對於長時間執行的代理任務，Python、TypeScript 和 Ruby 的 tool runner 支援自動壓縮（compaction），當 token 使用量超過閾值時會產生摘要，使對話能夠超越「context window」（上下文視窗）限制繼續進行。這三個 SDK 都已棄用此客戶端選項，改為使用伺服器端的上下文編輯，後者在每個 SDK 中都可使用。Go、Java、C# 和 PHP 的 tool runner 不包含客戶端壓縮功能。



偵錯工具執行

當工具拋出例外時，tool runner 會捕捉它並將錯誤以 is_error: true 的工具結果形式回傳給 Claude。工具結果包含例外的訊息（在 Python 中為其型別和訊息），而非完整的堆疊追蹤。

SDK 記錄的內容因語言而異。每當工具引發未處理的例外時，Python SDK 會透過標準 logging 模組記錄完整的例外（包括其堆疊追蹤）。Python、TypeScript 和 Java SDK 會讀取 ANTHROPIC_LOG 環境變數以開啟 SDK 的日誌記錄，其中包含請求和回應的詳細資訊：

# 以 info 層級記錄
export ANTHROPIC_LOG=info

# 以 debug 層級記錄以取得更詳細的輸出
export ANTHROPIC_LOG=debug

Go、Ruby、C# 和 PHP SDK 不會讀取 ANTHROPIC_LOG。除了 Python 之外，沒有 SDK 會記錄失敗的工具：若要查看工具失敗的原因，請在工具函式內捕捉並記錄例外，然後再回傳或重新拋出它。



攔截工具錯誤

預設情況下，工具錯誤會傳回給 Claude，Claude 可以據此做出適當的回應。然而，您可能希望偵測錯誤並以不同方式處理它們，例如提早停止執行或實作自訂錯誤處理。

在 Python 和 TypeScript SDK 中，使用工具回應方法（Python 中的 generate_tool_call_response()、TypeScript 中的 generateToolResponse()）在工具結果發送給 Claude 之前攔截並檢查錯誤。其他 SDK 不提供該掛鉤。它們的分頁描述了最接近的替代方案：



修改工具結果

您可以在工具結果發送回 Claude 之前修改它們。這對於新增中繼資料（例如 cache_control）以在工具結果上啟用提示快取，或轉換工具輸出非常有用。

在 Python 和 TypeScript SDK 中，使用工具回應方法取得工具結果，然後在 runner 繼續之前修改它。您是明確附加修改後的結果還是就地變更它，取決於 SDK。請參閱每個分頁中的程式碼註解。



串流

啟用「streaming」（串流）以逐步處理每個回合的回應。每次迭代會產出一個串流物件，您可以迭代它以取得事件。



後續步驟