跳轉到主要內容
工具搜尋使您的代理能夠通過動態發現和按需加載來處理數百或數千個工具。代理不是將所有工具定義預先加載到上下文窗口中,而是搜尋您的工具目錄並僅加載它需要的工具。 隨著工具庫的擴展,這種方法解決了兩個挑戰:
  • 上下文效率: 工具定義可能會消耗上下文窗口的大部分(50 個工具可能使用 10-20K 個令牌),留下較少的空間用於實際工作。
  • 工具選擇準確性: 同時加載超過 30-50 個工具時,工具選擇準確性會下降。
工具搜尋預設為啟用。

工具搜尋的工作原理

當工具搜尋處於活動狀態時,工具定義會從上下文窗口中隱藏。代理會收到可用工具的摘要,並在任務需要尚未加載的功能時搜尋相關工具。最相關的五個工具會被加載到上下文中,在後續輪次中保持可用。如果對話足夠長,以至於 SDK 壓縮早期消息以釋放空間,之前發現的工具可能會被移除,代理會根據需要再次搜尋。 工具搜尋在 Claude 首次發現工具時增加一個額外的往返(搜尋步驟),但對於大型工具集,這會被每個輪次上下文較小所抵消。對於少於約 10 個工具的情況,預先加載所有工具通常更快。 有關底層 API 機制的詳細信息,請參閱 API 中的工具搜尋
工具搜尋在 Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 及更新版本上受支援;請參閱 API 文件中的模型相容性以取得目前清單。在 Google Cloud 的 Agent Platform 上,最低支援的模型是 Claude Sonnet 4.5 和 Claude Opus 4.5。
工具搜尋預設為開啟。在 Google Cloud 的 Agent Platform 上預設為關閉,其中支援 Claude Sonnet 4.5 及更高版本以及 Claude Opus 4.5 及更高版本。當 ANTHROPIC_BASE_URL 指向非第一方主機時,它也會被禁用,因為大多數代理不轉發 tool_reference 塊。您可以使用 ENABLE_TOOL_SEARCH 環境變數覆蓋任一預設值: 設置 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 會保持工具搜尋關閉,且 ENABLE_TOOL_SEARCH 無法覆蓋它。該變數會移除 defer_loading 工具定義和 tool_reference 內容塊所需的 beta 標頭。 工具搜尋適用於所有已註冊的工具,無論它們來自遠端 MCP 伺服器還是自訂 SDK MCP 伺服器。使用 auto 時,閾值基於所有伺服器上所有工具定義的組合大小。 query() 上的 env 選項中設置該值。在 TypeScript 中,env 會取代子程序環境,因此請展開 ...process.env 以保留繼承的變數。在 Python 中,env 會合併到繼承的環境之上。此示例連接到公開許多工具的遠端 MCP 伺服器,使用萬用字元預先批准所有工具,並使用 auto:5 以便在工具定義超過上下文窗口的 5% 時啟動工具搜尋:
若要執行此示例,請將 https://tools.example.com/mcp 替換為您自己的 MCP 伺服器的 URL。成功時,結果文字會列印到主控台。 因為這是單次 query() 呼叫,SDK 會在產生錯誤結果後引發,所以此示例會將迴圈包裝在 try 區塊中。若要查看執行失敗的原因,請檢查結果訊息的 subtype(例如 error_during_execution)在迴圈內。如需有關結果訊息的詳細資訊,請參閱處理結果 ENABLE_TOOL_SEARCH 設置為 "false" 會禁用工具搜尋,並在每個輪次將所有工具定義加載到上下文中。這會移除搜尋往返,當工具集較小(少於約 10 個工具)且定義舒適地適應上下文窗口時,這可能會更快。

優化工具發現

搜尋機制將查詢與工具名稱和描述進行匹配。search_slack_messages 之類的名稱比 query_slack 適用於更廣泛的請求。具有特定關鍵字的描述(「按關鍵字、頻道或日期範圍搜尋 Slack 消息」)比通用描述(「查詢 Slack」)匹配更多查詢。 您也可以添加一個系統提示部分,列出可用的工具類別。這為代理提供了有關可搜尋的工具類型的上下文。通過 TypeScript 中的 systemPrompt 選項或 Python 中的 system_prompt 傳遞文本,使用 claude_code 預設搭配 append,這會將您的文本添加到預設的提示中,而不是替換它:
如需完整的系統提示選項集合,請參閱修改系統提示

限制

  • 最大工具數: 您的目錄中有 10,000 個工具
  • 搜尋結果: 預設情況下每次搜尋返回最多五個最相關的工具
  • 模型支援: Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5 及更新版本;請參閱 API 文件中的模型相容性以取得目前清單。在 Google Cloud 的 Agent Platform 上,支援 Claude Sonnet 4.5 及更新版本和 Claude Opus 4.5 及更新版本。