Масштабирование на множество инструментов с помощью поиска инструментов
Масштабируйте вашего агента на тысячи инструментов, обнаруживая и загружая только необходимое по требованию.
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.
Configure tool search
Tool search включен по умолчанию. Он отключен по умолчанию на Vertex AI, где он поддерживается для Claude Sonnet 4.5 и более поздних версий, а также Claude Opus 4.5 и более поздних версий. Он также отключен, когда ANTHROPIC_BASE_URL указывает на хост, не принадлежащий первой стороне, поскольку большинство прокси не пересылают блоки tool_reference. Вы можете переопределить любое значение по умолчанию с помощью переменной окружения ENABLE_TOOL_SEARCH:
| Значение | Поведение |
|---|---|
| (не установлено) | Tool search включен. Определения инструментов отложены и обнаруживаются по требованию. Возвращается к загрузке заранее на Vertex AI или при использовании ANTHROPIC_BASE_URL, не принадлежащего первой стороне. |
true |
Tool search всегда включен. SDK отправляет заголовок beta даже на Vertex AI и через прокси. Запросы не выполняются на моделях Vertex AI более ранних версий, чем Sonnet 4.5 или Opus 4.5, или на прокси, которые не поддерживают блоки tool_reference. |
auto |
Проверяет объединенное количество токенов всех определений инструментов в сравнении с окном контекста модели. Если они превышают 10%, tool search активируется. Если они менее 10%, все инструменты загружаются в контекст обычным образом. |
auto:N |
То же, что auto, но с пользовательским процентом. auto:5 активируется, когда определения инструментов превышают 5% окна контекста. Более низкие значения активируются раньше. |
false |
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 Sonnet 4 и более поздние версии, Claude Opus 4 и более поздние версии (без Haiku)
Related documentation
- Tool search в API: Полная документация API для tool search, включая пользовательские реализации
- Подключение MCP серверов: Подключение к внешним инструментам через MCP серверы
- Пользовательские инструменты: Создавайте свои собственные инструменты с помощью SDK MCP серверов
- Справочник TypeScript SDK: Полный справочник API
- Справочник Python SDK: Полный справочник API