Tool Runner (SDK)

Tool Runner（SDK）

Tool Runner 處理代理迴圈、錯誤包裝和類型安全，所以您不必這樣做。只有當您需要人工審批、自訂日誌記錄或條件執行時，才使用手動迴圈。可在 Python、TypeScript 和 Ruby SDK 中使用。

Tool Runner 為使用 Claude 執行工具提供了開箱即用的解決方案。Tool Runner 不是手動處理工具呼叫、工具結果和對話管理，而是自動執行以下操作：

對大多數工具使用實現使用 Tool Runner。

Tool Runner 目前處於測試版，可在 Python、TypeScript 和 Ruby SDK 中使用。

使用壓縮進行自動上下文管理

Tool Runner 支援自動壓縮，當令牌使用量超過閾值時會生成摘要。這允許長時間執行的代理任務超越上下文視窗限制。

基本用法

使用 SDK 助手定義工具，然後使用 Tool Runner 執行它們。

工具函數必須返回內容區塊或內容區塊陣列，包括文本、圖像或文件區塊。這允許工具返回豐富的多模態回應。返回的字符串將被轉換為文本內容區塊。如果您想將結構化 JSON 物件返回給 Claude，請在返回前將其編碼為 JSON 字符串。數字、布林值或其他非字符串基本類型也必須轉換為字符串。

Tool Runner 是一個可迭代物件，從 Claude 產生訊息。這通常稱為「工具呼叫迴圈」。每次迭代時，Runner 檢查 Claude 是否請求了工具使用。如果是，它會呼叫工具並自動將結果發送回 Claude，然後產生來自 Claude 的下一條訊息以繼續您的迴圈。

您可以在任何迭代中使用 break 語句結束迴圈。Runner 將迴圈直到 Claude 返回沒有工具使用的訊息。

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

在迴圈內，您可以完全自訂 Tool Runner 對 Messages API 的下一個請求。Runner 會自動將工具結果附加到訊息歷史記錄中，因此您不需要手動管理它們。您可以選擇檢查工具結果以進行日誌記錄或偵錯，並在下一個 API 呼叫之前修改請求參數。

當工具拋出異常時，Tool Runner 會捕捉它並將錯誤作為工具結果返回給 Claude，其中 is_error: true。預設情況下，只包含異常訊息，不包含完整堆疊追蹤。

要查看完整堆疊追蹤和偵錯資訊，請設定 ANTHROPIC_LOG 環境變數：

# View info-level logs including tool errors
export ANTHROPIC_LOG=info

# View debug-level logs for more verbose output
export ANTHROPIC_LOG=debug

啟用後，SDK 會記錄完整的異常詳細資訊（在 Python 中使用 logging 模組、在 TypeScript 中使用控制台，或在 Ruby 中使用記錄器），包括工具失敗時的完整堆疊追蹤。

預設情況下，工具錯誤會傳回給 Claude，然後它可以適當地回應。但是，您可能想要檢測錯誤並以不同方式處理它們，例如提前停止執行或實現自訂錯誤處理。

使用工具回應方法攔截工具結果並在將其發送給 Claude 之前檢查錯誤：

您可以在工具結果發送回 Claude 之前修改它們。這對於添加 cache_control 等元資料以在工具結果上啟用提示快取或轉換工具輸出很有用。

使用工具回應方法獲取工具結果，然後在 Runner 繼續之前修改它。無論您是明確附加修改後的結果還是就地變更它，都取決於 SDK；請參閱每個標籤中的程式碼註解。

將 cache_control 添加到工具結果特別有用，當工具返回大量資料（如文件搜尋結果）時，您想要為後續 API 呼叫快取這些資料。有關快取策略的更多詳細資訊，請參閱提示快取。

啟用串流以在事件到達時接收它們。每次迭代都會產生一個串流物件，您可以迭代以獲取事件。