Claude Code官方文档Agent SDK工具搜索

Claude Agent SDK 工具搜索 - 扩展到数千个工具

通过按需发现和加载工具，将代理扩展到数千个工具。（原文为英文，已翻译）

发布于 2025年5月1日 · 阅读约 7 分钟

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

随着工具库的扩展，这种方法解决了两个挑战：

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

工具搜索的工作原理

当工具搜索处于活动状态时，工具定义会从上下文窗口中保留。代理收到可用工具的摘要，并在任务需要尚未加载的功能时搜索相关工具。最相关的 3-5 个工具被加载到上下文中，并在后续回合中保持可用。如果对话足够长，SDK 压缩较早的消息以释放空间，则先前发现的工具可能会被删除，并且代理会根据需要再次搜索。

工具搜索在 Claude 首次发现工具时（搜索步骤）增加了一次额外的往返，但对于大型工具集，每次回合上的上下文都更小，因此可以抵消这一开销。在工具少于约 10 个时，预先加载所有内容通常更快。

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

ℹ️ 工具搜索需要 Claude Sonnet 4 或更高版本，或 Claude Opus 4 或更高版本。Haiku 模型不支持工具搜索。

配置工具搜索

默认情况下，工具搜索始终开启。你可以使用 ENABLE_TOOL_SEARCH 环境变量更改此项：

值	行为
（未设置）	工具搜索始终开启。工具定义永远不会加载到上下文中。这是默认值。
`true`	与未设置相同。
`auto`	检查所有工具定义的合并 token 计数与模型的上下文窗口的对比。如果它们超过 10%，则激活工具搜索。如果它们低于 10%，则所有工具都正常加载到上下文中。
`auto:N`	与 `auto` 相同，但带有自定义百分比。`auto:5` 在工具定义超过上下文窗口的 5% 时激活。较低的值会更快激活。
`false`	工具搜索关闭。每个回合都将所有工具定义加载到上下文中。

工具搜索适用于所有已注册的工具，无论它们来自远程 MCP 服务器还是自定义 SDK MCP 服务器。使用 auto 时，阈值基于所有服务器上所有工具定义的合并大小。

在 query() 的 env 选项上设置该值。此示例连接到暴露许多工具的远程 MCP 服务器，使用通配符预先批准所有工具，并使用 auto:5，以便当它们的定义超过上下文窗口的 5% 时激活工具搜索：

TypeScript

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

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: {
      ENABLE_TOOL_SEARCH: "auto:5" // Activate tool search when tools exceed 5% of context
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Python

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "enterprise-tools": {
                "type": "http",
                "url": "https://tools.example.com/mcp",
            }
        },
        allowed_tools=[
            "mcp__enterprise-tools__*"
        ],  # Wildcard pre-approves all tools from this server
        env={
            "ENABLE_TOOL_SEARCH": "auto:5"  # Activate tool search when tools exceed 5% of context
        },
    )

    async for message in query(
        prompt="Find and run the appropriate database query",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

将 ENABLE_TOOL_SEARCH 设置为 "false" 会禁用工具搜索，并在每个回合将所有工具定义加载到上下文中。这消除了搜索往返，当工具集较小（少于约 10 个工具）且定义可舒适地放入上下文窗口时可能更快。

优化工具发现

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

你还可以添加一个系统提示部分，列出可用的工具类别。这为代理提供了有关可搜索的工具种类的上下文：

You can search for tools to interact with Slack, GitHub, and Jira.

限制

最大工具数： 目录中 10,000 个工具
搜索结果： 每次搜索返回最相关的 3-5 个工具
模型支持： Claude Sonnet 4 及更高版本，Claude Opus 4 及更高版本（不支持 Haiku）

工具搜索的工作原理

配置工具搜索

TypeScript

Python

优化工具发现

限制

相关文档