Настройка 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: tool_search и defer_loading

Настроить 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-hydrogen
  • gemini-4-argon
  • gemini-3.8-flash
  • gemini-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 modeldefer_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 на реальном трафике вместе с итоговыми списаниями.

Готовы оптимизировать LLM workflow?

Подключите единый API, управляйте ключами и контролируйте расходы на AI-модели в BetterToken.

Начать бесплатно