SpyBara
Go Premium

agent-sdk/tool-search.md 2026-09-09 22:58 UTC to 2026-09-10 23:00 UTC

This page contains 30 additions and 25 deletions.

2026
Thu 10 23:00

使用工具搜索扩展到多个工具

通过动态发现和按需加载，将您的代理扩展到数千个工具。

工具搜索使您的代理能够通过动态发现和按需加载来处理数百或数千个工具。代理不是将所有工具定义预先加载到上下文窗口中，而是搜索您的工具目录并仅加载它需要的工具。

当工具库扩展时，这种方法解决了两个挑战：

  • 上下文效率： 工具定义可能会消耗上下文窗口的大部分（50个工具可能使用10-20K个令牌），留下较少的空间用于实际工作。
  • 工具选择准确性： 一次加载超过30-50个工具时，工具选择准确性会下降。

工具搜索的工作原理

工具搜索默认处于启用状态，配置工具搜索中列出的情况除外。

当工具搜索处于活动状态时，工具定义会从上下文窗口中隐藏。代理会收到可用工具的摘要，并在任务需要尚未加载的功能时搜索相关工具。最多五个最相关的工具被默认加载到上下文中，在后续轮次中保持可用，直到SDK压缩代理发现它们的消息。在该压缩之后，代理在下次需要这些工具时会再次搜索它们。

工具搜索在Claude每次搜索工具时增加一个额外的往返，但对于大型工具集，这被每个轮次中较小的上下文所抵消。对于少于约10个工具且其定义能够舒适地放入上下文窗口的情况，预先加载所有工具通常更快。

有关底层API机制的详细信息，请参阅API中的工具搜索。

工具搜索默认启用。对于SDK的不支持模型列表中的模型，SDK会预先加载工具定义，而不是使用ENABLE_TOOL_SEARCH值覆盖。在Google Cloud的Agent Platform上，SDK根据模型代数决定：

  • Claude Opus 4.5、Sonnet 4.5、Haiku 4.5及更高版本：工具搜索默认启用。
  • 早期Agent Platform模型：SDK预先加载工具定义，因为它们的服务堆栈拒绝所需的beta标头。ENABLE_TOOL_SEARCH无法覆盖此行为。

在Claude Code v2.1.221之前，SDK会为Google Cloud的Agent Platform上的所有模型禁用工具搜索，除非您设置ENABLE_TOOL_SEARCH。

当ANTHROPIC_BASE_URL指向非第一方主机时，SDK也会禁用工具搜索，因为大多数代理不转发tool_reference块。您可以使用ENABLE_TOOL_SEARCH环境变量覆盖该默认值：

值 行为
（未设置） 工具搜索启用。工具定义被延迟并按需发现。在Google Cloud的Agent Platform早于Claude 4.5代的模型、非第一方ANTHROPIC_BASE_URL或Microsoft Foundry部署（托管在Azure上）上回退到预先加载。
true 工具搜索始终启用，除了在Microsoft Foundry部署（托管在Azure上）上，服务器端拒绝仍会强制预先加载，以及在Google Cloud的Agent Platform早于Claude 4.5代的模型上，SDK继续预先加载工具定义。SDK通过代理发送beta标头，在不支持tool_reference块的代理上请求会失败。
auto 计算工具搜索可以延迟的工具定义中的令牌，并将总数与模型的上下文窗口进行比较。当总数达到窗口的10%时，工具搜索激活。低于此值时，SDK预先将每个工具定义加载到上下文中。
auto:N 与auto相同，但具有自定义百分比。auto:5在这些定义达到上下文窗口的5%时激活。较低的值更早激活。
false 工具搜索关闭。所有工具定义在每个轮次上都加载到上下文中。

设置CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS会保持工具搜索关闭。您无法通过自己设置ENABLE_TOOL_SEARCH来覆盖它。您的组织可以通过托管设置在Claude Code v2.1.227或更高版本上保持工具搜索启用。禁用预发布功能涵盖了覆盖应用的位置以及变量删除的内容。

工具搜索适用于所有已注册的工具，无论它们来自远程MCP服务器还是自定义SDK MCP服务器。当您使用auto时，SDK会计算工具搜索可以延迟的每个定义，针对一个组合阈值：来自任何服务器的未标记为alwaysLoad的每个MCP工具，加上按需加载的内置工具。SDK始终预先加载核心内置工具（如Bash、Read和Edit），不会将其计入阈值。

在query()上的env选项中设置值。在TypeScript中，env替换子进程环境，因此展开...process.env以保持继承的变量。在Python中，env合并到继承的环境之上。此示例连接到公开许多工具的远程MCP服务器，使用通配符预先批准所有工具，并使用auto:5，以便当工具搜索可以延迟的定义达到上下文窗口的5%时激活工具搜索：

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
for await (const message of query({
prompt: "Find and run the appropriate database query",
options: {
mcpServers: {
"enterprise-tools": {
// Connect to a remote MCP server
type: "http",
url: "https://tools.example.com/mcp"
}
},
allowedTools: ["mcp__enterprise-tools__*"], // Wildcard pre-approves all tools from this server
env: {
...process.env, // env replaces the subprocess environment, so keep inherited variables
ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when deferrable definitions reach 5% of context
}
}
})) {
if (message.type === "result" && message.subtype === "success") {
console.log(message.result);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result
console.log(`Session ended with an error: ${error}`);
}

要运行此示例，请将https://tools.example.com/mcp替换为您自己的MCP服务器的URL。成功时，结果文本会打印到控制台。

因为这是一个单次query()调用，SDK在产生错误结果后会抛出异常，所以该示例将循环包装在try块中。要查看运行失败的原因，请检查循环内结果消息的subtype，例如error_during_execution。有关结果消息的更多信息，请参阅处理结果。

优化工具发现

搜索机制将查询与工具名称和描述进行匹配。像search_slack_messages这样的名称比query_slack更广泛地出现在各种请求中。具有特定关键字的描述（"按关键字、频道或日期范围搜索Slack消息"）比通用描述（"查询Slack"）匹配更多查询。

您还可以添加一个系统提示部分，列出可用的工具类别。这为代理提供了关于可以搜索什么类型工具的上下文。通过 TypeScript 中的 systemPrompt 选项或 Python 中的 system_prompt 传递文本，使用带有 append 的 claude_code 预设，这会将您的文本添加到预设的提示中，而不是替换它：

options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "You can search for tools to interact with Slack, GitHub, and Jira."
}
}

有关完整的系统提示选项集，请参阅修改系统提示。

限制

  • 最大工具数： 您的目录中最多10,000个工具
  • 搜索结果： 默认每次搜索返回最多五个最相关的工具
  • 模型支持： Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5及更新版本；请参阅API文档中的模型兼容性了解当前列表。Google Cloud的Agent Platform上也适用相同的最低要求。