AIKraft Agents
Главная/Блог/Гайд/Gemini API Tool Retrieval: Как…
Гайд11 мин чтения · 22 ноября 2026 г.

Gemini API Tool Retrieval: Как оптимизировать работу с сотнями инструментов

Разбираем новую функцию Gemini API Tool Retrieval: как отложенная загрузка схем инструментов снижает затраты на токены и ускоряет работу агентов.

Gemini API Tool Retrieval: Как оптимизировать работу с сотнями инструментов

Развитие агентов на базе больших языковых моделей (LLM) часто упирается в одну фундаментальную проблему: контекстное окно. Чем больше инструментов (функций, API, баз данных) доступно агенту, тем больше токенов требуется для передачи их описаний модели. Это не просто вопрос стоимости — это вопрос задержки (latency) и стабильности работы. Google ответила на этот вызов, представив функцию Tool Retrieval в Gemini API, которая сейчас находится в стадии предварительного просмотра (preview) в Interactions API. Эта технология меняет парадигму взаимодействия между приложением и моделью, позволяя хранить обширные библиотеки инструментов без необходимости отправлять их полные схемы в каждом запросе.

В традиционном подходе, если у вас есть агент, подключенный к десяткам или сотням функций, вы обязаны включать определения всех этих инструментов в промпт. Даже если агенту нужна только одна функция для выполнения конкретной задачи, модель «видит» все остальные, что приводит к огромным накладным расходам. Tool Retrieval предлагает элегантное решение: модель видит только названия и краткие описания инструментов, а полные схемы параметров загружаются только тогда, когда это действительно необходимо. Это снижает потребление токенов, уменьшает задержки и делает возможным создание более сложных и многофункциональных AI-агентов.

В этой статье мы подробно разберем, как работает эта технология, какие есть режимы работы (серверный и клиентский), как она взаимодействует с MCP (Model Context Protocol) и кэшированием, а также сравним ее с аналогами от Anthropic и OpenAI. Мы также рассмотрим финансовые аспекты и практические рекомендации по внедрению.

01Что такое Gemini API Tool Retrieval и зачем она нужна?

Суть функции Tool Retrieval заключается в механизме отложенной загрузки (deferred loading). Согласно документации Google, основная проблема, которую решает эта фича, — это потребление десятков тысяч токенов на каждый запрос, когда объявляется несколько десятков функций. Вместо того чтобы отправлять полные JSON-схемы всех доступных инструментов в каждом обращении к API, модель получает только имена инструментов и их краткие описания.

Это позволяет агенту «знать» о существовании огромного количества инструментов, не перегружая контекстное окно. Когда модели требуется выполнить действие, связанное с одним из этих инструментов, она запрашивает его полное описание. Только после этого API возвращает полную схему параметров, необходимую для формирования корректного вызова функции. Такой подход критически важен для агентов, работающих с динамическими или обширными наборами данных, где количество доступных действий может варьироваться от десятков до тысяч.

Важно отметить, что эта функция не отменяет необходимость предоставления контекста. Модель по-прежнему должна понимать, какие инструменты доступны, чтобы принять решение о их использовании. Однако, смещая акцент с детальных схем на семантические описания, Google позволяет значительно сократить объем передаваемых данных, сохраняя при этом функциональную полноту агента.

02Как работает отложенная загрузка (defer_loading) в Interactions API

Для использования этой возможности разработчикам необходимо внести изменения в структуру запроса к API. В массив tools добавляется специальный объект с типом {"type": "tool_search"}. Затем, для каждой функции, которую вы хотите сделать «отложенной», устанавливается флаг defer_loading: true. Это указывает модели, что полные детали этой функции не должны быть включены в текущий промпт.

Пример из официального поста Google для разработчиков демонстрирует функцию issue_refund (возврат средств), работающую на модели gemini-4-hydrogen. В комментариях к коду упоминается, что таких отложенных функций может быть более 50. Это наглядно показывает масштаб оптимизации: вместо отправки 50 полных схем, модель работает с легковесным списком.

Gemini API Tool Retrieval: Как оптимизировать работу с сотнями инструментов

Процесс взаимодействия при использовании отложенных инструментов состоит из трех четких шагов, которые API обрабатывает автоматически:

  1. tool_search_call: Модель определяет, что ей нужен конкретный инструмент, и отправляет запрос на его поиск по имени.
  2. tool_search_result: API отвечает, возвращая полную схему параметров (schema) для запрошенного инструмента.
  3. function_call: Используя полученную схему, модель формирует корректный вызов функции, который ваше приложение должно выполнить.

Ключевой момент здесь заключается в том, что первые два шага (поиск и загрузка схемы) разрешаются самим API. Ваше приложение получает только финальный function_call, который вы исполняете, а затем возвращаете результат через function_result. Это упрощает архитектуру приложения, так как вам не нужно самостоятельно управлять логикой поиска и кэширования схем в большинстве случаев.

💡
Совет по использованию. Отложенные функции могут содержать необязательное поле short_description. Это описание отображается во время процесса извлечения и валидно только тогда, когда установлен флаг defer_loading: true. Используйте это поле для предоставления наиболее релевантной информации, которая поможет модели правильно выбрать инструмент, не раскрывая всех технических деталей.

03Серверный vs Клиентский режим извлечения

Google предлагает два режима работы функции Tool Retrieval, каждый из которых подходит для разных сценариев использования. Выбор между ними зависит от ваших требований к безопасности, кастомизации и инфраструктуре.

Серверный режим (Server-side)

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

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

Клиентский режим (Client-side)

Для случаев, когда требуется больший контроль, доступен клиентский режим. Он активируется путем установки параметра "execution": "client". В этом режиме ваше приложение само выполняет поиск. Вы можете использовать собственную базу данных, индекс эмбеддингов (embeddings), реестр инструментов или фильтры прав доступа.

Gemini API Tool Retrieval: Как оптимизировать работу с сотнями инструментов

После того как ваше приложение находит подходящие объявления, оно возвращает их в поле function_result.result. Эти инструменты могут быть добавлены в контекст разговора даже в середине сессии, если они отсутствовали в первоначальном массиве tools. Однако у этого режима есть существенный недостаток: каждый поиск на стороне клиента требует дополнительного сетевого запроса (round trip), что увеличивает задержку.

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

04Взаимодействие с MCP и кэшированием

Одним из ключевых трендов в области AI-агентов является использование Model Context Protocol (MCP). Tool Retrieval хорошо интегрируется с MCP, что делает ее особенно привлекательной для разработчиков, строящих экосистему связанных инструментов.

Если вы установите defer_loading: true для записи mcp_server, то все инструменты, предоставляемые этим сервером, будут отложены. При этом отложенные инструменты MCP все равно выполняются удаленно через поддержку MCP в Gemini API. Это позволяет использовать преимущества стандартизированного протокола, не жертвуя эффективностью контекстного окна.

Что касается кэширования, то отложенные схемы остаются за пределами префикса промпта. Загруженные схемы добавляются в конец, поэтому неявное кэширование (implicit caching) все еще применяется. Однако документация предупреждает о нюансе: если отложенные инструменты уменьшают размер промпта ниже минимального порога, необходимого для кэширования, то кэширование может не сработать. Это важно учитывать при оптимизации затрат, так как потеря кэширования может привести к увеличению стоимости запросов.

⚠️ Важно.
Ограничение кэширования. Отложенные инструменты могут сократить размер промпта ниже минимального размера, необходимого для кэширования. Если ваш промпт становится слишком коротким после удаления схем инструментов, вы можете потерять преимущества кэширования, что увеличит затраты. Следите за размером контекста.

05Стоимость использования Tool Retrieval

Google не взимает отдельную плату за использование функции Tool Retrieval. Токены тарифицируются по стандартным ставкам модели: входные (input), кэшированные (cached) и выходные (output). Однако есть важные нюансы, влияющие на итоговую стоимость.

Каждый серверный поиск запускает дополнительный вызов модели над полным контекстом. Эти токены появляются в поле total_tool_use_tokens и тарифицируются по ставке input. После загрузки схема инструмента остается в контексте и тарифицируется как input на протяжении всего разговора. Это означает, что хотя вы экономите токены на старте, загруженные инструменты становятся частью постоянного контекста.

Gemini API Tool Retrieval: Как оптимизировать работу с сотнями инструментов

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

Для оценки затрат рекомендуется использовать инструменты мониторинга, такие как расширение Chrome GPULeaderboard.com, которое позволяет проверять параметры развертывания и спецификации. Это поможет вам точно рассчитать стоимость для вашего конкретного сценария использования.

06Сравнение с инструментами Anthropic и OpenAI

Конкуренты Google также предлагают аналогичные функции поиска инструментов. Anthropic (Tool Search Tool) и OpenAI (tool search) уже внедрили подобные возможности, и их показатели эффективности часто используются как эталон. Однако прямое сравнение требует осторожности, так как данные о экономии токенов и точности часто являются самоотчетными и основаны на внутренних тестах компаний.

Ниже приведена таблица сравнения ключевых характеристик:

Характеристика Gemini API Tool Retrieval Anthropic Tool Search Tool OpenAI tool search
Статус Preview, v1beta Не раскрыто на странице документации Не раскрыто на странице документации
API поверхность Только Interactions API Messages API; Bedrock InvokeModel Responses API
Модели Gemini 4 Carbon, Neon, Hydrogen, Argon; 3.8 Flash; 3.6 Flash Claude 5 series, Opus 4.5+, Sonnet 4.5+, Haiku 4.5 gpt-5.4 и новее
Режимы поиска Серверный или клиентский Regex, BM25 или пользовательский Хостится или выполняется клиентом
Макс. отложенных инструментов Не раскрыто 10,000 Не раскрыто
Результатов на поиск Не раскрыто 5 по умолчанию Не раскрыто
Поддержка MCP На уровне записи mcp_server На уровне mcp_toolset На уровне инструмента MCP-сервера
Отдельная плата Нет Нет Не раскрыто
Опубликованная экономия токенов Отсутствует 85% (с 77K до 8.7K токенов) 47% на 250 задачах MCP Atlas
Опубликованная точность Отсутствует Opus 4.5: 79.5% - 88.1% Не раскрыто

Как видно из таблицы, Anthropic сообщает о значительной экономии токенов (85%) и высокой точности для своих моделей. OpenAI также делится данными об экономии (47%). Google на данный момент не опубликовала аналогичных данных. Это не означает, что Gemini работает хуже, но указывает на то, что результаты могут варьироваться в зависимости от конкретного использования. Разработчикам следует проводить собственные тесты для оценки эффективности в своих сценариях.

07Практические рекомендации по внедрению

При внедрении Gemini API Tool Retrieval в свои проекты, следует учитывать несколько практических аспектов. Во-первых, начните с небольшой группы инструментов. Не откладывайте все инструменты сразу. Протестируйте, как модель справляется с поиском и загрузкой схем, и оцените влияние на задержку и стоимость.

Во-вторых, тщательно продумайте short_description. Поскольку модель принимает решение о выборе инструмента на основе этих описаний, они должны быть максимально информативными и точными. Плохо составленные описания могут привести к ошибкам в выборе инструмента, что потребует дополнительных итераций и увеличит затраты.

Gemini API Tool Retrieval: Как оптимизировать работу с сотнями инструментов

В-третьих, рассмотрите возможность использования клиентского режима, если у вас есть специфические требования к безопасности или кастомизации. Например, если вы работаете с чувствительными данными, вы можете использовать клиентский поиск для фильтрации инструментов на основе прав доступа пользователя перед тем, как передать их модели. Однако будьте готовы к дополнительным затратам на сетевые запросы.

Наконец, мониторьте использование кэширования. Как упоминалось ранее, отложенные инструменты могут повлиять на эффективность кэширования. Используйте инструменты аналитики, чтобы отслеживать, как часто срабатывает кэширование, и корректируйте размер промпта accordingly.

📌 Факт.
Доступность в РФ. Gemini API доступен для разработчиков из России. Однако, из-за санкций, некоторые способы оплаты могут быть ограничены. Рекомендуется использовать виртуальные карты международных банков или сервисы-посредники для оплаты токенов. Также можно рассмотреть локальные развертывания моделей Gemini, если это возможно в вашей инфраструктуре.

08Что это значит на практике

Внедрение Gemini API Tool Retrieval открывает новые возможности для создания сложных AI-агентов, которые могут взаимодействовать с десятками и сотнями инструментов без катастрофического роста стоимости и задержки. Это особенно важно для приложений, таких как виртуальные ассистенты, автоматизация бизнес-процессов и интеллектуальные поисковые системы, где количество доступных действий может быть очень большим.

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

Сравнение с конкурентами показывает, что Google предлагает гибкое решение с двумя режимами работы, что позволяет адаптировать его под различные потребности. Отсутствие опубликованных данных об экономии токенов пока не позволяет сделать окончательные выводы о эффективности по сравнению с Anthropic и OpenAI, но предварительные тесты показывают многообещающие результаты.

В конечном итоге, Gemini API Tool Retrieval — это мощный инструмент, который может значительно улучшить масштабируемость и эффективность AI-агентов. Разработчикам следует активно экспериментировать с этой функцией, чтобы найти оптимальный баланс между функциональностью, стоимостью и производительностью для своих конкретных проектов.

09Заключение

Tool Retrieval в Gemini API представляет собой значительный шаг вперед в области управления контекстом для AI-агентов. Позволяя откладывать загрузку схем инструментов, эта функция решает одну из самых больших проблем в разработке LLM-приложений — перегрузку контекстного окна. Хотя есть некоторые нюансы, связанные с кэшированием и стоимостью, преимущества использования этой технологии перевешивают недостатки для большинства сценариев использования с большим количеством инструментов.

Разработчикам рекомендуется начать с изучения документации Google, попробовать функцию в Interactions API v1beta и провести собственные тесты для оценки эффективности в их конкретных сценариях. По мере развития технологии, мы ожидаем появления большего количества данных об эффективности и лучших практик использования.

Следите за обновлениями в блоге Google и на платформах сообщества, чтобы быть в курсе последних новостей и улучшений в области AI-инфраструктуры. Tool Retrieval — это не просто новая функция, это новый подход к построению масштабируемых и эффективных AI-систем.

Источник: MarkTechPost ↗