Масштабирование на множество инструментов с помощью поиска инструментов

Масштабируйте вашего агента на тысячи инструментов, обнаруживая и загружая только необходимое по требованию.

Tool search позволяет вашему агенту работать с сотнями или тысячами инструментов, динамически обнаруживая и загружая их по требованию. Вместо загрузки всех определений инструментов в окно контекста заранее, агент ищет в каталоге инструментов и загружает только необходимые ему инструменты.

Этот подход решает две проблемы при масштабировании библиотек инструментов:

• Эффективность контекста: Определения инструментов могут занимать большую часть окна контекста (50 инструментов могут использовать 10-20K токенов), оставляя меньше места для фактической работы.
• Точность выбора инструмента: Точность выбора инструмента снижается при загрузке более 30-50 инструментов одновременно.

Tool search включен по умолчанию. На этой странице рассматривается как это работает, как настроить его и как оптимизировать обнаружение инструментов.

How tool search works

Когда tool search активен, определения инструментов исключаются из окна контекста. Агент получает сводку доступных инструментов и ищет релевантные, когда задача требует возможности, которая еще не загружена. 3-5 наиболее релевантных инструментов загружаются в контекст, где они остаются доступными для последующих ходов. Если разговор достаточно длинный, чтобы SDK компактировал более ранние сообщения для освобождения места, ранее обнаруженные инструменты могут быть удалены, и агент снова ищет по мере необходимости.

Tool search добавляет один дополнительный обмен данными в первый раз, когда Claude обнаруживает инструмент (этап поиска), но для больших наборов инструментов это компенсируется меньшим контекстом на каждом ходу. При наличии менее ~10 инструментов загрузка всего заранее обычно быстрее.

Для получения подробной информации об основном механизме API см. Tool search в API.

Настройка поиска инструментов

Tool search включен по умолчанию. Он отключен по умолчанию на Vertex AI, где он поддерживается для Claude Sonnet 4.5 и более поздних версий, а также Claude Opus 4.5 и более поздних версий. Он также отключен, когда ANTHROPIC_BASE_URL указывает на хост, не принадлежащий первой стороне, поскольку большинство прокси не пересылают блоки tool_reference. Вы можете переопределить любое значение по умолчанию с помощью переменной окружения ENABLE_TOOL_SEARCH:

Tool search применяется ко всем зарегистрированным инструментам, независимо от того, поступают ли они с удаленных MCP серверов или пользовательских SDK MCP серверов. При использовании auto пороговое значение основано на объединенном размере всех определений инструментов на всех серверах.

Установите значение в опции env на query(). Этот пример подключается к удаленному MCP серверу, который предоставляет множество инструментов, предварительно одобряет все их с помощью подстановочного символа и использует auto:5, чтобы tool search активировался, когда их определения превышают 5% окна контекста:

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);
}
}

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" отключает tool search и загружает все определения инструментов в контекст на каждом ходу. Это удаляет раунд поиска, что может быть быстрее, когда набор инструментов небольшой (менее ~10 инструментов) и определения удобно помещаются в окно контекста.

Optimize tool discovery

Механизм поиска сопоставляет запросы с именами и описаниями инструментов. Имена вроде search_slack_messages появляются для более широкого диапазона запросов, чем query_slack. Описания с конкретными ключевыми словами ("Search Slack messages by keyword, channel, or date range") соответствуют большему количеству запросов, чем общие ("Query Slack").

Вы также можете добавить раздел системного приглашения, в котором перечислены доступные категории инструментов. Это дает агенту контекст о том, какие виды инструментов доступны для поиска:

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

Limits

• Максимальное количество инструментов: 10 000 инструментов в вашем каталоге
• Результаты поиска: Возвращает 3-5 наиболее релевантных инструментов на поиск
• Поддержка модели: каждая модель Claude, кроме Haiku

Связанная документация

• Tool search в API: Полная документация API для tool search, включая пользовательские реализации
• Подключение MCP серверов: Подключение к внешним инструментам через MCP серверы
• Пользовательские инструменты: Создавайте свои собственные инструменты с помощью SDK MCP серверов
• Справочник TypeScript SDK: Полный справочник API
• Справочник Python SDK: Полный справочник API