Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
工具搜索工具使 Claude 能够通过动态发现和按需加载来处理数百或数千个工具。与其将所有工具定义预先加载到上下文窗口中，Claude 会搜索您的工具目录（包括工具名称、描述、参数名称和参数描述），并仅加载它需要的工具。
当工具库扩展时，这种方法解决了两个关键挑战：
虽然这是作为服务器端工具提供的，但您也可以实现自己的客户端工具搜索功能。有关详细信息，请参阅自定义工具搜索实现。
工具搜索工具目前处于公开测试版。为您的提供商包含适当的测试版标头：
| 提供商 | 测试版标头 | 支持的模型 |
|---|---|---|
| Claude API Microsoft Foundry | advanced-tool-use-2025-11-20 | Claude Opus 4.5 Claude Sonnet 4.5 |
| Google Cloud 的 Vertex AI | tool-search-tool-2025-10-19 | Claude Opus 4.5 Claude Sonnet 4.5 |
| Amazon Bedrock | tool-search-tool-2025-10-19 | Claude Opus 4.5 |
在 Amazon Bedrock 上，服务器端工具搜索仅通过调用 API 可用，不支持反向 API。
您也可以通过从自己的搜索实现返回 tool_reference 块来实现客户端工具搜索。
有两种工具搜索变体：
tool_search_tool_regex_20251119)：Claude 构造正则表达式模式来搜索工具tool_search_tool_bm25_20251119)：Claude 使用自然语言查询来搜索工具启用工具搜索工具时：
tool_search_tool_regex_20251119 或 tool_search_tool_bm25_20251119）defer_loading: truetool_reference 块这样可以保持上下文窗口高效，同时维持高工具选择准确性。
这是一个带有延迟工具的简单示例：
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: advanced-tool-use-2025-11-20" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 2048,
"messages": [
{
"role": "user",
"content": "What is the weather in San Francisco?"
}
],
"tools": [
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"name": "get_weather",
"description": "Get the weather at a specific location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"]
}
},
"required": ["location"]
},
"defer_loading": true
},
{
"name": "search_files",
"description": "Search through files in the workspace",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string"},
"file_types": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["query"]
},
"defer_loading": true
}
]
}'工具搜索工具有两种变体：
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
}{
"type": "tool_search_tool_bm25_20251119",
"name": "tool_search_tool_bm25"
}正则表达式变体查询格式：Python 正则表达式，不是自然语言
使用 tool_search_tool_regex_20251119 时，Claude 使用 Python 的 re.search() 语法构造正则表达式模式，而不是自然语言查询。常见模式：
"weather" - 匹配包含"weather"的工具名称/描述"get_.*_data" - 匹配 get_user_data、get_weather_data 等工具"database.*query|query.*database" - 用于灵活性的 OR 模式"(?i)slack" - 不区分大小写的搜索最大查询长度：200 个字符
BM25 变体查询格式：自然语言
使用 tool_search_tool_bm25_20251119 时，Claude 使用自然语言查询来搜索工具。
通过添加 defer_loading: true 标记工具以按需加载：
{
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
},
"required": ["location"]
},
"defer_loading": true
}关键点：
defer_loading 的工具会立即加载到上下文中defer_loading: true 的工具仅在 Claude 通过搜索发现它们时加载defer_loading: true两种工具搜索变体（regex 和 bm25）都搜索工具名称、描述、参数名称和参数描述。
当 Claude 使用工具搜索工具时，响应包括新的块类型：
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "I'll search for tools to help with the weather information."
},
{
"type": "server_tool_use",
"id": "srvtoolu_01ABC123",
"name": "tool_search_tool_regex",
"input": {
"query": "weather"
}
},
{
"type": "tool_search_tool_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": {
"type": "tool_search_tool_search_result",
"tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
}
},
{
"type": "text",
"text": "I found a weather tool. Let me get the weather for San Francisco."
},
{
"type": "tool_use",
"id": "toolu_01XYZ789",
"name": "get_weather",
"input": { "location": "San Francisco", "unit": "fahrenheit" }
}
],
"stop_reason": "tool_use"
}server_tool_use：表示 Claude 正在调用工具搜索工具tool_search_tool_result：包含搜索结果，其中包含嵌套的 tool_search_tool_search_result 对象tool_references：指向发现的工具的 tool_reference 对象数组tool_use：Claude 调用发现的工具tool_reference 块会自动扩展为完整的工具定义，然后显示给 Claude。您不需要自己处理这个扩展。只要您在 tools 参数中提供所有匹配的工具定义，它就会在 API 中自动发生。
工具搜索工具与 MCP 服务器 配合使用。将 "mcp-client-2025-11-20" 测试版标头 添加到您的 API 请求中，然后使用带有 default_config 的 mcp_toolset 来延迟加载 MCP 工具：
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
--header "content-type: application/json" \
--data '{
"model": "claude-sonnet-4-5-20250929",
"max_tokens": 2048,
"mcp_servers": [
{
"type": "url",
"name": "database-server",
"url": "https://mcp-db.example.com"
}
],
"tools": [
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"type": "mcp_toolset",
"mcp_server_name": "database-server",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"defer_loading": false
}
}
}
],
"messages": [
{
"role": "user",
"content": "What events are in my database?"
}
]
}'MCP 配置选项：
default_config.defer_loading：为来自 MCP 服务器的所有工具设置默认值configs：按名称覆盖特定工具的默认值您可以通过从自定义工具返回 tool_reference 块来实现自己的工具搜索逻辑（例如，使用嵌入或语义搜索）：
{
"type": "tool_search_tool_result",
"tool_use_id": "toolu_custom_search",
"content": {
"type": "tool_search_tool_search_result",
"tool_references": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}
}每个引用的工具必须在顶级 tools 参数中有相应的工具定义，并设置 defer_loading: true。这种方法让您可以使用更复杂的搜索算法，同时保持与工具搜索系统的兼容性。
有关使用嵌入的完整示例，请参阅我们的带嵌入的工具搜索 cookbook。
工具搜索工具与工具使用示例不兼容。如果您需要提供工具使用示例，请使用不带工具搜索的标准工具调用。
这些错误会阻止请求被处理：
所有工具都延迟：
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "All tools have defer_loading set. At least one tool must be non-deferred."
}
}缺少工具定义：
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Tool reference 'unknown_tool' has no corresponding tool definition"
}
}工具执行期间的错误返回 200 响应，错误信息在正文中：
{
"type": "tool_result",
"tool_use_id": "srvtoolu_01ABC123",
"content": {
"type": "tool_search_tool_result_error",
"error_code": "invalid_pattern"
}
}错误代码：
too_many_requests：工具搜索操作超过速率限制invalid_pattern：格式错误的正则表达式模式pattern_too_long：模式超过 200 个字符限制unavailable：工具搜索服务暂时不可用工具搜索与提示缓存配合使用。添加 cache_control 断点以优化多轮对话：
import anthropic
client = anthropic.Anthropic()
# 第一个带工具搜索的请求
messages = [
{
"role": "user",
"content": "What's the weather in Seattle?"
}
]
response1 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
betas=["advanced-tool-use-2025-11-20"],
max_tokens=2048,
messages=messages,
tools=[
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"name": "get_weather",
"description": "Get weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
},
"defer_loading": True
}
]
)
# 将 Claude 的响应添加到对话中
messages.append({
"role": "assistant",
"content": response1.content
})
# 带缓存断点的第二个请求
messages.append({
"role": "user",
"content": "What about New York?",
"cache_control": {"type": "ephemeral"}
})
response2 = client.beta.messages.create(
model="claude-sonnet-4-5-20250929",
betas=["advanced-tool-use-2025-11-20"],
max_tokens=2048,
messages=messages,
tools=[
{
"type": "tool_search_tool_regex_20251119",
"name": "tool_search_tool_regex"
},
{
"name": "get_weather",
"description": "Get weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
},
"defer_loading": True
}
]
)
print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")系统会自动在整个对话历史中扩展 tool_reference 块，因此 Claude 可以在后续轮次中重用发现的工具，而无需重新搜索。
启用流式传输后，您将接收工具搜索事件作为流的一部分：
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}
// 搜索查询流式传输
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}
// 搜索执行时暂停
// 搜索结果流式传输
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}
// Claude 继续使用发现的工具您可以在消息批处理 API 中包含工具搜索工具。通过消息批处理 API 的工具搜索操作的定价与常规消息 API 请求中的相同。
良好的用例：
传统工具调用可能更好的情况：
工具搜索工具的使用情况在响应使用对象中跟踪：
{
"usage": {
"input_tokens": 1024,
"output_tokens": 256,
"server_tool_use": {
"tool_search_requests": 2
}
}
}