AI

Tool Retrieval у Gemini API: завантаження схем інструментів на вимогу в Interactions API

Редакція LinksGauge3 хв читання

Схема роботи функції Tool Retrieval у Gemini API з пошуком інструментів і завантаженням схем

Головне за 30 секунд

  • Tool Retrieval доступний у прев'ю в Interactions API і працює з Gemini 3.6 і пізнішими моделями, включно з Gemini 4.
  • Модель бачить назву й опис відкладених інструментів, а повні схеми параметрів підвантажуються лише за потреби в межах одного запиту.
  • Пошук виконується на сервері Google без потреби будувати власний індекс, а відкладені схеми не руйнують кеш префікса.
  • Окремої плати за Tool Retrieval немає, але клієнтський пошук додає один додатковий обмін запитом і відповіддю.
Зміст

Google представила Tool Retrieval у Gemini API — функцію, яка наразі доступна у прев'ю в Interactions API. Вона дозволяє агентам тримати великі набори інструментів у режимі очікування та завантажувати схеми параметрів лише тоді, коли цього вимагає поточне завдання, замість того щоб передавати повну бібліотеку в кожному запиті.

Коли агент підключений до десятків чи сотень інструментів, передача повних схем параметрів у кожному запиті швидко збільшує кількість вхідних токенів, додає затримку та знижує точність вибору інструмента зі зростанням списку варіантів. Функція підтримується у моделях Gemini 3.6 і пізніших, зокрема у всіх моделях Gemini 4.

Як працює відкладене завантаження та налагодження

Щоб увімкнути Tool Retrieval, до запиту додають інструмент tool_search, а для інструментів, які потрібно відкласти, встановлюють defer_loading: true. Модель усе одно бачить назву та опис кожного відкладеного інструмента, але схеми параметрів залишаються поза контекстом до моменту потреби.

Коли моделі потрібен конкретний інструмент, вона запитує його за назвою, API завантажує повну схему, і модель викликає функцію — усе в межах одного запиту. Наприклад, під час одного виклику API модель може знайти issue_refund, отримати його схему та сформувати function_call, а всі три кроки з'являться в interaction.steps. Це спрощує перевірку того, які саме інструменти розглядала модель, під час налагодження назв або описів, після чого виконання функції та повернення function_result відбуваються у звичайному режимі.

Серверний і клієнтський режими, кешування та тарифікація

Пошук виконується на стороні сервера Gemini, тому розробникам не потрібно створювати або підтримувати власний індекс: достатньо додати новий інструмент і прапорець відкладеного завантаження. Найчастіше використовувані інструменти можна лишати завантаженими одразу, а рідкісні — відкладати.

Рішення узгоджується з кешуванням префікса, оскільки відкладені схеми не потрапляють на початок промпта, а завантажені додаються далі в розмові, тож кешований префікс не змінюється від ходу до ходу. Також Tool Retrieval працює з віддаленими MCP-серверами в Gemini API: достатньо задати defer_loading: true для інструмента mcp_server, щоб усі інструменти цього сервера завантажувалися на вимогу без переліку кожного окремо.

Якщо ж команда підтримує власний реєстр інструментів, індекс вбудовувань або фільтр прав доступу для кожного користувача, можна оголосити tool_search із параметром "execution": "client" і задати власні параметри пошуку. У такому разі пошук виконує застосунок, що додає один раунд обміну запитом і відповіддю на кожен пошук, але дозволяє не оголошувати інструменти заздалегідь і додавати нові посеред розмови, коли користувач підключає інтеграцію.

Окремої плати за Tool Retrieval немає — вхідні та вихідні токени тарифікуються за стандартними ставками обраної моделі. Увімкнення tool_search додає невеликий фіксований блок вхідних токенів, а кожна завантажена схема оплачується як вхідні токени до кінця розмови так само, як і інструмент, оголошений одразу. Економія на токенах виникає тоді, коли незавантажені схеми переважають завантажені, що типово для великих бібліотек, і залежить від реального трафіку.

Що це означає на практиці

Для розробників, які будують ШІ-агентів із великим набором функцій або інтеграцій через MCP, Tool Retrieval дає спосіб стримувати зростання вхідних токенів і затримок без побудови власної пошукової інфраструктури. Водночас оскільки у тексті джерела не наведено конкретних цифр економії токенів чи приросту точності, командам варто перевірити роботу tool_search, defer_loading: true та interaction.steps на власному трафіку і сценаріях із Gemini 3.6 або Gemini 4, а також оцінити додаткову затримку у разі вибору клієнтського виконання "execution": "client".