Настройка Tool Retrieval в Gemini API: tool_search и defer_loading
Как настроить Tool Retrieval в превью Gemini Interactions API (v1beta) через tool_search и defer_loading. Сравниваем серверный и клиентский режимы, проверяем расхождение по моделям Gemini 4, настраиваем удаленный MCP и stateless-повтор, разбираем ошибки 400, биллинг и префиксное кеширование.
Содержание

Настроить Tool Retrieval в Gemini API теперь можно в превью Interactions API (v1beta): с tool_search и defer_loading агенты загружают JSON-схемы параметров инструментов по запросу. Функция касается разработчиков, которые подключают к Gemini десятки пользовательских функций или удаленные MCP-серверы, и работает только в Interactions API (метод generateContent ее не поддерживает). По состоянию на 2026-11-20 для запуска достаточно вызвать v1beta/interactions с одной из четырех задокументированных моделей (gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash или gemini-3.6-flash), добавить {"type": "tool_search"} и указать defer_loading: true для инструментов вне базового набора.
Сначала выберите маршрут API
Google представил Tool Retrieval 19 ноября 2026 года в официальном блоге Google и опубликовал руководство по настройке в документации AI Studio по Tool retrieval. Функция привязана к превью Interactions API (v1beta), поэтому выбор маршрута зависит от вашего текущего эндпоинта и региональных ограничений доступа.
| Маршрут | Аккаунт и регион | Единица тарификации | Поддержка Tool Retrieval | Когда выбирать |
|---|---|---|---|---|
Официальный Gemini Interactions API (v1beta) | Ключ Google AI Studio в поддерживаемом регионе (Россия в список стран по состоянию на 2026-11-20 не входит); для gemini-4-argon нужен Paid Tier | За 1M входных, кешированных и выходных токенов (для gemini-4-hydrogen, gemini-3.8-flash и gemini-3.6-flash доступен Standard Free Tier) | Доступна в превью (tool_search, defer_loading, удаленный mcp_server) | У вас крупная библиотека инструментов и есть прямой доступ к v1beta/interactions |
Официальный Gemini generateContent API | Тот же аккаунт Google AI Studio и поддерживаемый регион | За 1M входных, кешированных и выходных токенов | Не поддерживается | У вас меньше ~20 стабильных инструментов, нужно явное кеширование на поддерживаемых моделях Gemini 3 или 2.5 либо переезд на Interactions API пока невозможен |
| API-шлюз с оплатой по факту (например, BetterToken) | Аккаунт BetterToken и API-ключ из консоли; подключение к API-эндпоинту из России работает без VPN (это касается только эндпоинта, а не сторонних сайтов, загрузок, входов, маркетплейсов или обновлений); доступна оплата в рублях без зарубежной карты (конкретные каналы оплаты, подходящие карты, минимумы, курсы, комиссии и сроки зачисления зависят от консоли в момент оплаты) | Баланс с оплатой по факту по текущей расчетной единице модели | Interactions API не задокументирован; поддержка Tool Retrieval не подтверждена | Вы остаетесь на задокументированных нативном Gemini generateContent или OpenAI-совместимом Chat Completions сразу для нескольких моделей (поддержку инструментов по моделям уточняйте в документации BetterToken) |
Если вы продолжаете работать через стандартный Gemini generateContent или OpenAI-совместимый Chat Completions вместо перехода на Interactions API, можете изучить справочник BetterToken по Gemini API с перечнем задокументированных эндпоинтов, идентификаторов моделей и поддерживаемых инструментов.
Поддерживаемые модели и ошибка 400 в Gemini 4
В анонсе от 19 ноября 2026 года блог Google утверждает, что Tool Retrieval работает с Gemini 3.6 и более новыми моделями, включая все модели Gemini 4, и ссылается на страницу Latest Gemini models. На той странице перечислены четыре модели Gemini 4: gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen и gemini-4-argon.
Однако по состоянию на 2026-11-20 официальный список поддерживаемых моделей Tool retrieval включает только четыре идентификатора:
gemini-4-hydrogengemini-4-argongemini-3.8-flashgemini-3.6-flash
Модели gemini-4-carbon и gemini-4-neon на странице документации Tool Retrieval по состоянию на 2026-11-20 отсутствуют. Передача defer_loading в неподдерживаемую модель возвращает HTTP 400 с текстом deferred loading is not supported for this model.
Начинайте интеграцию с gemini-4-hydrogen, которую Google использует во всех примерах Tool Retrieval; если вы переходите с моделей Flash, посмотрите руководство по ценам и миграции на Gemini 4 Hydrogen. Если ваш сценарий завязан на gemini-4-carbon, проверьте фактическое поведение на v1beta перед включением defer_loading либо изучите разбор цен и миграции на Gemini 4 Carbon API и временно оставьте статическую загрузку инструментов.
Серверный и клиентский режимы поиска
Interactions API поддерживает два взаимоисключающих режима: серверный поиск (по умолчанию) и клиентский поиск (execution: "client"). Оба убирают схемы параметров из стартового промпта, но различаются по задержке, объему кода и способу регистрации инструментов.
| Параметр | Статическая загрузка | Серверный поиск | Клиентский поиск |
|---|---|---|---|
| Как схемы попадают к модели | Все отправляются сразу | Gemini подгружает отложенные схемы по требованию | Ваше приложение возвращает схемы в function_result |
| Код поиска на стороне клиента | Не нужен | Не нужен | Свой поиск, ранжирование и фильтрация |
| Предварительное объявление инструментов | Да | Да | Нет |
| Поддержка удаленного MCP | Да | Да (defer_loading: true на mcp_server) | Не применимо |
| Лишние сетевые раундтрипы | Нет | Нет (выполняется внутри одного вызова API) | Один раундтрип на каждый поиск |
| Лучший сценарий | Меньше ~20 стабильных инструментов | Большие фиксированные каталоги или несколько MCP-серверов | Закрытые реестры, права по пользователям, динамические инструменты в ходе сессии |
В одном запросе допускается только одна запись tool_search. Если объединить серверный и клиентский tool_search в одном вызове, API вернет ошибку Cannot specify both client-side and server-side tool_search tools..
Настройка серверного поиска и удаленного MCP
Серверный поиск требует версию API v1beta. Хотя пример кода в блоге Google опускает параметр api_version, официальное руководство по Tool retrieval прямо указывает на необходимость v1beta: в Python инициализируйте клиент как genai.Client(http_options={"api_version": "v1beta"}), а в JavaScript — как new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }).
В оболочке Bash считайте ключ Gemini API без вывода на экран и отправьте POST-запрос на https://generativelanguage.googleapis.com/v1beta/interactions. Пример ниже сочетает отложенную локальную функцию (convert_currency) и задокументированный демо-сервер погоды Google по MCP (https://gemini-api-demos.uc.r.appspot.com/mcp):
read -rs GEMINI_API_KEY && export GEMINI_API_KEY
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-hydrogen",
"input": "Check the temperature in London and convert 100 USD to EUR.",
"tools": [
{"type": "tool_search"},
{
"type": "function",
"name": "convert_currency",
"description": "Convert an amount from one currency to another using live mid-market rates.",
"short_description": "Convert an amount between currencies.",
"defer_loading": true,
"parameters": {
"type": "object",
"properties": {
"amount": {"type": "number"},
"from": {"type": "string"},
"to": {"type": "string"}
},
"required": ["amount", "from", "to"]
}
},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": true
}
]
}'
При сборке массива tools соблюдайте четыре правила:
- Не задавайте
name,descriptionиparametersв серверном объектеtool_search. - Передавайте полную схему
parametersдля каждой отложеннойfunction. Незагруженные схемы не тарифицируются, а функция безparametersвернется из поиска с пустой схемой, и модель не сможет ее вызвать. - Используйте необязательное поле
short_descriptionтолько вместе сdefer_loading: true, чтобы сократить длинныйdescriptionв компактном списке отложенных инструментов. - Для удаленных MCP-серверов подключайте только эндпоинты Streamable HTTP (серверы SSE не поддерживаются) и задавайте имена серверов в
snake_caseбез дефиса-, как описано в разделе Remote MCP. Если удаленный сервер падает на рукопожатии или валидации схемы, воспользуйтесь руководством по диагностике интеграции MCP-серверов.
Как проверить ответ при серверном поиске
Успешный ответ серверного поиска содержит шаги tool_search_call и tool_search_result внутри массива steps в том же вызове API, а сразу за ними идет фактический вызов инструмента. Для удаленных MCP-инструментов вроде get_weather на демо-сервере API также сам выполняет удаленный вызов и возвращает шаги mcp_server_tool_call и mcp_server_tool_result в том же ответе.
Для своих локальных функций ищите элементы function_call напрямую в steps. Не ориентируйтесь только на проверку status == "requires_action": Google предупреждает, что status не всегда принимает значение requires_action, даже когда в ответе есть шаг function_call. Выполните функцию локально и отправьте function_result на следующем ходе.
Настройка клиентского поиска
Выбирайте execution: "client", когда каталог инструментов зависит от прав конкретного пользователя, внутренних пространств имен или интеграций, подключенных уже после старта сессии. Для клиентского tool_search оба поля name и description обязательны (пропуск любого из них дает ошибку 400), а defer_loading нельзя ставить ни на один инструмент в запросе.
Сниппет на Python ниже показывает минимальный протокольный пример: он возвращает фиксированное объявление вместо запроса к живому реестру. Проверить корректность обмена можно по выводу скрипта — он должен напечатать шаг function_call для get_billing_history с аргументами {"user_id": 123} из followup.steps:
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
tools = [
{
"type": "tool_search",
"execution": "client",
"name": "search_tool_registry",
"description": "Search internal tool namespaces such as billing and support when needed.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"namespace": {"type": "string"},
},
"required": ["query"],
},
}
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Look up the billing history for user 123.",
tools=tools,
)
for step in interaction.steps:
if step.type == "function_call" and step.name == "search_tool_registry":
# Minimal protocol example: replace with your own registry or permission filter.
matches = [
{
"type": "function",
"name": "get_billing_history",
"description": "Retrieve billing history for a given user.",
"parameters": {
"type": "object",
"properties": {"user_id": {"type": "integer"}},
"required": ["user_id"],
},
}
]
followup = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=interaction.id,
tools=tools,
input=[
{
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": matches,
}
],
)
for next_step in followup.steps:
if next_step.type == "function_call":
print(next_step.name, next_step.arguments)
Возвращайте полные объявления функций как JSON-объекты внутри массива function_result.result, а не как сериализованную JSON-строку, и обязательно передавайте совпадающие name и call_id из поискового function_call. Если клиентский поиск ничего не нашел, верните короткий текстовый ответ о том, что совпадений нет, и перечислите доступные направления поиска, чтобы модель уточнила запрос.
Многошаговые диалоги, stateless-повтор и частые ошибки
Три ограничения превью могут приводить к сбоям интеграции после первого хода:
- Отправляйте полный массив
toolsв каждом запросе. Interactions API сохраняет историю шагов при передачеprevious_interaction_id, но не хранит объявления инструментов между запросами. Если опуститьtoolsв последующем ходе, модель пропустит необъявленные инструменты или начнет выдавать внутренние вызовы с префиксомretriever:в серверном режиме. - Загруженные инструменты нельзя выгрузить, а пустой серверный поиск возвращает текст. Как только модель подгрузила схему инструмента, она остается в контексте до конца диалога. Если серверный запрос не нашел ни одного отложенного инструмента, API возвращает обычный текстовый ответ без структурированной ошибки поиска, поэтому на шаг
tool_search_resultдля отлова промахов полагаться нельзя. - Передавайте шаги и
signatureбез изменений приstore=false. В каждом stateless-запросе передавайте всю историю шагов вinputи снова отправляйте полный массивtools. Добавляйте все шаги ответа (tool_search_call,tool_search_result,thoughtиfunction_call) в исходном порядке с сохраненным полемsignature, а уже после них — новыйfunction_result. Если отправить толькоfunction_result, контекст поиска пропадет и API вернет400. Используйте версию SDK, которая распознаетtool_search_callиtool_search_result: старые версии разбирают их как неизвестные шаги и теряют поля. Любой инструмент, упомянутый по имени в системных инструкциях или в выводе другого инструмента, объявляйте безdefer_loading: иначе модель может вызвать его без поиска, а API отклонит последующий запрос сfunction_resultошибкой400.
Google документирует ошибки HTTP 400 для неподдерживаемых моделей, отсутствующего серверного tool_search при defer_loading, поля short_description без defer_loading: true, пропущенных name или description в клиентском режиме, недостающих stateless-шагов и потерянных значений signature. В таблице собраны точные сообщения и способы исправления:
| Задокументированное сообщение об ошибке | Причина | Исправление |
|---|---|---|
deferred loading is not supported for this model | defer_loading передан в модель вне списка поддерживаемых | Переключитесь на gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash или gemini-3.6-flash |
tool_search tool must be specified when using defer_loading. | У function или mcp_server указан defer_loading: true, но в запросе нет инструмента tool_search | Добавьте {"type": "tool_search"} или уберите defer_loading |
When defer_loading is set on a FunctionDeclaration, a Tool with tool_search must also be provided in the request. | У функции задан defer_loading: true, но нет серверного tool_search (например, объявлен только execution: "client" или в повторном запросе забыли tool_search) | Уберите defer_loading в клиентском режиме или передайте полный массив tools с {"type": "tool_search"} |
Cannot specify both client-side and server-side tool_search tools. | В одном запросе указаны сразу серверный и клиентский tool_search | Оставьте ровно один объект tool_search на запрос |
ToolSearch name must not be specified when execution mode is SERVER_SIDE. | В серверном tool_search задано поле name (та же ошибка приходит для description и parameters) | Удалите поле; при переходе на execution: "client" укажите оба поля name и description и уберите defer_loading со всех инструментов |
short_description can only be set if defer_loading is true | У функции задан short_description без defer_loading: true | Добавьте defer_loading: true или уберите short_description |
Server side tool call context must be circulated when using deferred loading functions. | В stateless-запросе есть function_result для отложенного инструмента, но нет шагов tool_search_call и tool_search_result, которые его загрузили | Передайте назад все шаги tool_search_call и tool_search_result без изменений, включая signature |
Server side tool call context must be circulated ... Missing circulated context for functions: FUNCTION_NAME (даже если все шаги возвращены) | Модель вызвала отложенную функцию без tool_search — обычно потому, что ее имя попало в системный промпт или вывод другого инструмента | Не ставьте defer_loading на инструменты, названные по имени в инструкциях или ответах |
Tool call part is missing thought_signature. / Tool response part is missing thought_signature. | В stateless-запросе шаг tool_search_call (часть вызова) или tool_search_result (часть ответа) отправлен назад без поля signature | Возвращайте оба шага поиска целиком с сохраненными значениями signature |
Поля биллинга, префиксное кеширование и точка окупаемости
Отдельной платы за Tool Retrieval нет. Все токены списываются по стандартным входным, кешированным и выходным ставкам со страницы цен Gemini API. По состоянию на 2026-11-20 модель gemini-4-hydrogen на Paid Tier стоит $1.50 за 1M входных токенов, $0.075 за 1M кешированных входных токенов и $7.50 за 1M выходных токенов (включая токены рассуждений). Standard Free Tier доступен для gemini-4-hydrogen, gemini-3.8-flash и gemini-3.6-flash, тогда как gemini-4-argon работает только на Paid Tier по цене $2.00 за вход, $0.10 за кеш и $10.00 за выход за 1M токенов до 30 ноября 2026 года, а с 1 декабря 2026 года тариф вырастает до $4.00 / $0.20 / $20.00.
Для контроля расхода проверяйте пять полей usage в каждом ответе взаимодействия:
total_input_tokens: промпт первого вызова модели в запросе — ваш ввод, история диалога, системные инструкции, схемы неотложенных инструментов, небольшой фиксированный блок инструкцийtool_searchи однострочные записи отложенных инструментов (nameплюсshort_descriptionили первое предложениеdescription, около 26 токенов на отложенный инструмент по ранним тестам Google).total_tool_use_tokens: промпты дополнительных вызовов модели, которые API выполняет внутри того же запроса после срабатывания серверного инструмента, включая каждый серверный поиск. Каждый такой проход снова отправляет полный контекст плюс загруженные схемы и тарифицируется по входной ставке; несколько поисков за один ход добавляют несколько проходов.total_cached_tokens: часть промпта, обслуженная из неявного кеша по кешированной ставке вместо обычной входной.total_output_tokens: сгенерированные токены ответа по выходной ставке.total_thought_tokens: сгенерированные токены рассуждений по выходной ставке.
Ограничение по порогу префиксного кеширования
Interactions API поддерживает только неявное кеширование (implicit caching): явное кеширование недоступно ни в Interactions API, ни для моделей Gemini 4, согласно странице Context caching. Поскольку найденные схемы добавляются в диалог в момент загрузки, а не в начало промпта, системные инструкции, список инструментов и ранние ходы образуют стабильный префикс. Когда этот префикс превышает минимальный размер для кеширования, последующие запросы в диалоге — включая дополнительный проход модели при серверном поиске — могут обслуживаться из неявного кеша и попадать в total_cached_tokens.
При этом по состоянию на 2026-11-20 все четыре модели с поддержкой Tool Retrieval требуют минимум 4 096 входных токенов для неявного кеширования. Если ваш промпт преодолевал отметку 4 096 токенов только за счет полных схем инструментов, перевод этих инструментов в отложенные может опустить запрос ниже порога кеширования. В многошаговых диалогах и агентных циклах на моделях Gemini 4 система кеширует предыдущий запрос целиком, только если новый запрос добавляет минимум 2 050 токенов (учитываются вывод модели, рассуждения и результаты функций); при меньшем приросте Gemini заново обрабатывает последние 2 050 токенов предыдущего запроса по стандартной входной ставке.
Когда Tool Retrieval экономит токены, а когда обходится дороже
В документации Google приведена ориентировочная оценка на два запроса (округленные числа, без учета выходных токенов и кеширования): модель загружает два инструмента по 400 токенов и возвращает function_call в первом запросе, а во втором получает function_result:
| Ориентировочный сценарий (оценка из документации Google) | Статическая загрузка (входные токены) | Tool Retrieval (входные + tool-use токены) | Итог |
|---|---|---|---|
| 200 инструментов (по 400 токенов), контекст 2 000 токенов | 2 × (2 000 + 80 000) = 164 000 | Запрос 1: 7 350 + проход поиска 8 150; Запрос 2: 8 150 = ~23 650 | Экономия ~86% входных токенов |
| 10 инструментов (по 400 токенов), контекст 30 000 токенов | 2 × (30 000 + 4 000) = 68 000 | Запрос 1: 30 410 + проход поиска 31 210; Запрос 2: 31 210 = ~92 830 | Расход выше на ~37% входных токенов |
Отложенная загрузка окупается при большом каталоге инструментов, когда большинство ходов затрагивает лишь несколько функций. На маленьком наборе инструментов или в длинном диалоге с поиском почти на каждом шаге дополнительный серверный проход (total_tool_use_tokens) способен перекрыть экономию. Оставьте самые частые инструменты загруженными сразу, переведите редкие в defer_loading: true и перед широким раскатыванием замерьте total_input_tokens, total_tool_use_tokens и total_cached_tokens на реальном трафике вместе с итоговыми списаниями.