Tool Retrieval в Gemini API: схемы по запросу и без отдельной цены

19 ноября 2026 года Google открыла в Gemini API Tool Retrieval. Если у агента десятки функций, полные схемы параметров больше не обязаны ехать в каждом запросе: имя и описание остаются, схему API подгружает, когда задача её требует. Заметку написали Lucia Loher, менеджер продукта Gemini API, и Nora Kassner, исследователь Google DeepMind: Introducing Tool Retrieval in the Gemini API.

Пока это preview и только Interactions API. Модель по-прежнему видит имя и описание каждого отложенного инструмента. В контекст не попадает именно схема параметров. Когда функций десятки или сотни, Google пишет три эффекта сразу: больше входных токенов, дольше ожидание и хуже выбор инструмента.

tool_search и defer_loading

Включается двумя правками. В список tools добавляют инструмент с типом tool_search. У функций, которые не нужны на каждом ходу, ставят defer_loading: true. Когда модель просит инструмент по имени, API подкладывает полную схему, и модель вызывает функцию. Поиск, подгрузка схемы и вызов идут внутри одного запроса.

В примере Google модель gemini-4-hydrogen, заказ A-1042 приехал повреждённым, вернуть 40 долларов, функция issue_refund. В том же примере после неё ещё 50 с лишним отложенных функций, частые просят оставить без флага.

from google import genai

client = genai.Client()

tools = [
    {"type": "tool_search"},
    {
        "type": "function",
        "name": "issue_refund",
        "description": "Refund an order to the original payment method.",
        "defer_loading": True,
        "parameters": {
            "type": "object",
            "properties": {
                "order_id": {"type": "string"},
                "amount": {"type": "number"},
            },
            "required": ["order_id", "amount"],
        },
    },
]

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Order A-1042 arrived damaged. Please refund 40 dollars.",
    tools=tools,
)

Внутри этого вызова модель ищет issue_refund, API отдаёт схему, модель присылает function_call. Три шага лежат в interaction.steps: tool_search_call, tool_search_result и function_call. В примере у вызова аргументы order_id A-1042 и amount 40. По шагам видно, какие имена модель вообще рассматривала, если описание кривое и выбор промахивается. Дальше обычный function calling: ваш код делает возврат и присылает function_result.

Поиск на сервере Gemini

Свой индекс строить и хостить не нужно. Поиск крутит сервер Gemini. В коде меняются две вещи: новый инструмент и флаг на тех функциях, которые хотите отложить. Редкие отложите. Частые оставьте в запросе сразу.

С кэшем префикса (prefix caching) это стыкуется. Отложенные схемы не стоят в начале промпта. То, что модель открыла, дописывается позже по ходу разговора. Кэшируемый префикс от хода к ходу один и тот же.

То же с удалённым MCP. На инструменте типа mcp_server ставят defer_loading: true, и каждый инструмент этого сервера подгружается по запросу. Перечислять их в запросе по одному не нужно. Раздел, на который ссылается заметка: remote MCP servers в Gemini API.

Свой реестр: execution client

Если реестр, свой индекс или разные права у разных людей уже у вас, tool_search объявляют иначе. Поле execution со значением client, параметры поиска ваши. В примере инструмент называется search_tools, на вход строка query.

Ищет ваше приложение, поэтому на каждый такой поиск добавляется ещё один запрос. Модель присылает function_call на search_tools, вы возвращаете подходящие схемы в function_result и продолжаете диалог через previous_interaction_id. В примере снова gemini-4-hydrogen. Заранее перечислять инструменты не нужно. Новый можно отдать посреди разговора, когда человек подключил интеграцию.

Серверному режиму свой индекс не нужен. Клиентский как раз для случая, когда индекс и права уже живут у вас.

Отдельной цены нет

Отдельного счёта у Tool Retrieval нет. Вход и выход идут по обычным тарифам той модели, которую вызвали. Сам tool_search добавляет небольшой фиксированный блок входных токенов. Каждая схема, которую модель открыла, дальше считается как вход до конца разговора, будто этот инструмент объявили сразу.

Экономия есть, когда неоткрытые схемы перевешивают открытые. Для большой библиотеки Google считает это обычным случаем и просит мерить на своём трафике. Если отложить функции, которые и так зовутся каждый ход, заплатите и за поиск, и за схемы.

Работает с Gemini 3.6 и новее, включая все модели Gemini 4, и только в Interactions API. Разбор настройки, на который ссылается анонс: документация tool retrieval.

Источники и ссылки


Комментарии загружаются…