Чтобы подключить Gemini Tool Retrieval, нужно сделать три вещи. Первое: добавить в массив tools элемент {"type": "tool_search"} и для редко используемых бизнес-функций указать defer_loading: True. Второе: отправить запрос через Interactions API версии v1beta, а затем найти function_call в interaction.steps. Третье: выполнить функцию локально, собрать function_result по call_id и отправить его обратно вместе с полным массивом tools. Свой поисковик инструментов писать не нужно — сервер сам выполняет поиск инструментов и загружает схемы параметров.
Сразу уточним: Tool Retrieval меняет только то, когда определения параметров инструментов попадают в контекст модели, — сами функции по-прежнему выполняет разработчик. И это не гарантирует экономию. В сценариях с малым числом инструментов и длинным контекстом расход токенов, наоборот, может вырасти.
Что вы узнаете из этой статьи?
- Какие модели поддерживает Gemini Tool Retrieval, какая версия SDK нужна и почему нужно явно указывать
v1beta - Полный пример на Python с одинаковыми именами переменных: два отложенных инструмента — склад и заказы — от поиска до финального ответа
- Кто обрабатывает
tool_search_call,tool_search_result,function_callиfunction_result - Чем отличаются три пути расширения: отложенная загрузка удалённого MCP, клиентский поиск и собственный Tool Registry
- Как системно диагностировать типичные ошибки вроде HTTP 400 и как до включения понять, окупится ли это
Навигация: сначала таблица «To Know» объясняет ключевые поля, затем «Краткий обзор влияния» рассказывает, что эта preview-функция значит для разных ролей. Раздел «Факты» идёт в порядке подключения: подготовка окружения, определение инструментов, наблюдение за шагами поиска, возврат результата функции, затем расширение до MCP и клиентского поиска; диагностика ошибок собрана в конце этого раздела. В разделе «Анализ и выводы» на двух гипотетических примерах расчёта от Google обсуждается, для каких сценариев Tool Retrieval подходит, а для каких — нет.

Ключевые концепции Gemini Tool Retrieval (что нужно знать)
| Концепция | Краткое объяснение |
|---|---|
| google-genai | Официальное имя пакета Python SDK от Google, импортируется через from google import genai |
| v1beta | Версия preview-интерфейса, обязательная для Tool Retrieval; в этой статье указывается явно при инициализации клиента |
| Interactions API | Интерфейс Google для агентных рабочих процессов, поддерживает диалоги с сохранением состояния и наблюдаемые шаги выполнения |
tool_search |
Специальный тип инструмента, объявляющий включение поиска инструментов; в одном запросе допускается не более одного |
defer_loading |
Заставляет полное определение параметров указанной функции или MCP-сервера загружаться в контекст модели с задержкой |
short_description |
Краткое описание отложенной функции, которое модель видит изначально; применимо только к отложенным функциям |
tool_search_call |
Шаг поиска, инициированный моделью в рамках серверного процесса поиска инструментов |
tool_search_result |
Шаг, на котором сервер возвращает полную Schema подходящего инструмента |
function_call |
Модель просит код разработчика выполнить функцию и передаёт аргументы |
function_result |
Тип входных данных, используемый приложением для возврата результата выполнения функции модели |
call_id |
Идентификатор, сопоставляющий результат выполнения функции с исходным function_call.id |
previous_interaction_id |
Идентификатор, позволяющий последующим запросам продолжать сохранённую на сервере запись взаимодействия |
signature |
Поле подписи, которое при воспроизведении истории шагов в stateless-сессии нужно передавать вместе с исходным шагом без изменений |
Gemini Tool Retrieval: кратко о влиянии
| Кому | Что на практике |
|---|---|
| Разработчики агентов | Агенты с большим числом инструментов могут отложенно загружать длиннохвостые инструменты — не придётся строить собственную векторную индексацию, но придётся перейти на Interactions API |
| Команды, которые уже используют generateContent | Старый метод не поддерживает Tool Retrieval: нужно мигрировать интерфейс и переделать разбор структуры ответа |
| Те, кто интегрирует MCP | Можно задать defer_loading целиком на уровне mcp_server и не объявлять каждый инструмент по отдельности |
| Ответственные за затраты | Отдельной платы за функцию нет, но каждый серверный поиск создаёт дополнительный тарифицируемый вызов модели — придётся следить за total_tool_use_tokens |
| Проекты с небольшим набором инструментов | В сценариях с десятком инструментов и длинным контекстом это может быть невыгодно; статическая загрузка может оказаться экономнее |
Gemini Tool Retrieval: что известно о релизе и как подключиться
Статус релиза Gemini Tool Retrieval и поддерживаемые модели
19 ноября 2026 года (по пекинскому времени — в ночь на 20 ноября), Google опубликовал в официальном блоге статью «Introducing Tool Retrieval in the Gemini API», открыв предварительный просмотр Tool Retrieval в Interactions API. Авторы — продакт-менеджер Gemini API Lucia Loher и научный сотрудник Google DeepMind Nora Kassner. Сейчас функция находится в статусе Preview, и до официального релиза интерфейс может измениться.
Формулировка в анонсе довольно широкая: «Gemini 3.6 и более новые модели, включая все модели Gemini 4». Однако в документации для разработчиков по состоянию на 20 ноября 2026 года явно указаны только 4 ID моделей: gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash. При интеграции стоит ориентироваться на список в документации. Если установить defer_loading для неподдерживаемой модели, вернётся HTTP 400.
Подготовка к подключению Gemini Tool Retrieval: SDK и v1beta
Официальный Python SDK от Google googleapis/python-genai 18 ноября 2026 года выпустил версию v3.6.0, в которой появились публичные схемы, связанные с Tool Retrieval и результатами функций. Команда установки:
pip install -U "google-genai>=3.6.0"
export GEMINI_API_KEY="your-key" # не записывайте настоящий ключ в код
С версией есть один подводный камень, на который легко наступить. Начиная с v3.0.0 клиент Gemini Developer API по умолчанию использует v1, а Tool Retrieval требует v1beta, поэтому при инициализации нужно явно указать версию:
from google import genai
client = genai.Client(
http_options={"api_version": "v1beta"}
)
SDK читает учётные данные из переменной окружения GEMINI_API_KEY. Если использовать REST, соответствующий endpoint — POST https://generativelanguage.googleapis.com/v1beta/interactions, а заголовок аутентификации — x-goog-api-key.
Шаг 1: Определяем инструменты Gemini через tool_search и defer_loading
В демо-сценарии всего два бизнес-инструмента: get_inventory ищет остатки товаров, get_order_status проверяет статус заказа — оба настроены на отложенную загрузку. Роли полей в массиве tools распределяются так:
{"type": "tool_search"}— включает серверный поиск, по умолчаниюexecutionравенserver. Без него настройкаdefer_loadingвыдаст ошибкуdefer_loading requires tool_search.defer_loading: True— полныйparametersне попадает в исходный контекст, модель поначалу видит только имя и краткое описание.short_description— краткое описание в исходном списке. Если не заполнить, берётся первое предложение изdescription. У неотложенной функции это поле указывать нельзя — посчитают недопустимым.parameters— всё равно нужно передавать полностью. Откладывается только момент попадания Schema в контекст модели, а серверу по-прежнему нужна полная спецификация.
Какие инструменты подходят для отложенной загрузки? Google советует смешанный подход: часто используемые держать загруженными напрямую, а редкие специализированные инструменты из «длинного хвоста» — откладывать. Ещё один момент: инструменты, которые прямо названы в системных инструкциях, лучше не делать отложенными. Иначе модель может обойти поиск и вызвать такой инструмент напрямую — и получит ошибку из-за отсутствия загруженного контекста. Для инструментов с похожими именами стоит добавлять бизнес-неймспейс: например, различать billing_get_customer и crm_get_customer, а не называть оба просто get_customer.
Шаг 2: Отправляем запрос и наблюдаем за шагами поиска инструментов
Ниже — полный демонстрационный код. Остаток «12 штук» и статус заказа demo_pending — это локальные имитационные данные, реальная система не запрашивается. Для запуска кода нужны действующий API-ключ Gemini и доступ к модели.
import json
from google import genai
MODEL = "gemini-4-hydrogen"
client = genai.Client(
http_options={"api_version": "v1beta"}
)
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "get_inventory",
"description": "Retrieve the available inventory for a product SKU.",
"short_description": "Check product inventory by SKU.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {"sku": {"type": "string"}},
"required": ["sku"]
}
},
{
"type": "function",
"name": "get_order_status",
"description": "Retrieve the status of a customer order.",
"short_description": "Check an order's current status.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"]
}
}
]
def execute_demo_tool(name, arguments):
"""Локальная имитационная бизнес-функция, реальные остатки и заказы не запрашиваются."""
if name == "get_inventory":
return {"sku": arguments["sku"], "available": 12, "data_source": "local_demo"}
if name == "get_order_status":
return {"order_id": arguments["order_id"], "status": "demo_pending", "data_source": "local_demo"}
raise ValueError(f"Unknown tool: {name}")
# Первый запрос: модель находит и выбирает нужные инструменты
interaction = client.interactions.create(
model=MODEL,
input="查询商品 SKU-42 的可用库存。",
tools=tools
)
print("执行步骤:")
for step in interaction.steps:
print(step.type, getattr(step, "name", ""))
Печатаемые interaction.steps обычно появляются в следующем порядке. Конкретный порядок и результаты поиска определяет модель; в рамках одного раунда поиск может выполняться несколько раз.
tool_search_call: модель обнаруживает, что среди уже загруженных инструментов нет подходящего, и запускает поиск на стороне сервера.tool_search_result: API возвращает полную схему параметров подходящегоget_inventory.function_call: прочитав схему, модель формирует вызов видаget_inventory(sku="SKU-42").
Эти три шага происходят в рамках одного и того же внешнего API-запроса; приложению не нужно отдельно писать поисковик и повторно отправлять запрос на поиск. Первые два шага нужно только наблюдать и фиксировать — не выполняйте поиск повторно локально. Но «один и тот же запрос» не означает «один прогон инференса»: каждый серверный поиск запускает дополнительный вызов модели, и эти токены тарифицируются как обычно. При отладке есть ещё один нюанс: нельзя смотреть только на interaction.status. Даже если статус не requires_action, в steps может оказаться ожидающий выполнения function_call.

Шаг 3: выполняем функцию и возвращаем function_result
Tool Retrieval отвечает только за поиск инструментов и загрузку параметров, а сами бизнес-функции по-прежнему выполняет приложение — здесь всё идёт по стандартному механизму Function Calling. Продолжаем код сверху:
# Выполняем только реальные бизнес-функции, tool_search_call на стороне приложения не вызываем
function_results = []
for step in interaction.steps:
if step.type != "function_call":
continue
result = execute_demo_tool(step.name, step.arguments)
function_results.append({
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": [{"type": "text", "text": json.dumps(result, ensure_ascii=False)}]
})
# Отправляем результаты локальных функций обратно в Gemini
if function_results:
followup = client.interactions.create(
model=MODEL,
previous_interaction_id=interaction.id,
tools=tools,
input=function_results
)
print("最终回答:", followup.output_text)
else:
print("当前回答:", interaction.output_text)
В этом коде есть три момента, на которые стоит обратить внимание. Первое: call_id должен браться из step.id исходного function_call. Когда в одном раунде несколько вызовов, именно по нему модель сопоставляет каждый результат. Второе: previous_interaction_id=interaction.id заставляет сервер продолжить сохранённую запись взаимодействия, включая уже найденные инструменты. Третье: на втором раунде всё равно нужно передавать весь массив tools. API сохраняет историю шагов, но не сохраняет объявления инструментов — tool_search, все отложенные и неотложенные инструменты, а также конфигурацию MCP нужно отправлять заново в каждом раунде.
Этот пример показывает только один замкнутый цикл вызова функции и не включает универсальный многотуровый диспетчер Agent. Если в followup снова появится function_call, просто продолжайте обработку тем же способом.
🎯 Совет: Tool Retrieval сам по себе опирается на официальный
v1betaInteractions API от Google. Если вы хотите сначала прогнать бизнес-функции через стандартный Function Calling и сравнить, как разные модели выбирают инструменты и заполняют параметры, можно в APIYI apiyi.com переключаться между Gemini, Claude, GPT и другими моделями по одному и тому же ключу и делать базовые тесты.
Расширение: удалённый MCP и клиентский поиск Gemini
Удалённые MCP-серверы могут настраивать ленивую загрузку на уровне самого сервера — их экспонируемые инструменты подгружаются по требованию:
mcp_tools = [
{"type": "tool_search"},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": True
}
]
В отличие от пользовательских функций, удалённые MCP-инструменты выполняет сам API — в steps появляются mcp_server_tool_call и mcp_server_tool_result, а приложению не нужно возвращать результат обратно. Официальная документация пока не указывает «максимальное число отложенных инструментов».
Если у компании уже есть собственный реестр инструментов, векторный поиск или фильтрация по правам пользователей, можно перейти на клиентский поиск: установите "execution": "client" и передайте полные name, description и parameters. В этом случае в первом раунде возвращается обычный function_call к search_tool_registry. После поиска в приложении верните в function_result.result массив полных объектов-объявлений инструментов, а не сериализуйте его в одну строку JSON. В клиентском режиме defer_loading не используется, и в одном запросе нельзя смешивать оба режима.

| Аспект | Серверный поиск | Клиентский поиск (Gemini) | Собственный Tool Registry (универсальное решение) |
|---|---|---|---|
| Кто выполняет поиск | Gemini API | Приложение разработчика | Приложение разработчика |
| Ключевая конфигурация | tool_search + defer_loading |
tool_search + execution: client |
Обычный Function Calling |
| Нужно ли заранее объявлять все инструменты | Да | Нет | Нет |
| Дополнительные сетевые обмены | Нет | +1 раунд на каждый поиск | +1 раунд на каждый поиск |
| Динамическое добавление инструментов | Неудобно | Поддерживается | Поддерживается |
| Типичные сценарии | Большие, относительно фиксированные библиотеки инструментов | Мультитенантность, приватный реестр | Повторное использование между моделями, переключение между вендорами |
| Доступные платформы | Официальный Google v1beta | Официальный Google v1beta | APIYI apiyi.com и другие OpenAI-совместимые интерфейсы |
Последняя колонка — это не Gemini Tool Retrieval, а инженерная реализация с похожей идеей: сначала экспонируем только одну функцию поиска, а после попадания в результат добавляем соответствующую Schema в tools. Она подходит командам, которым нужно переключаться между несколькими моделями. Минимальный вариант выглядит так:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIYI_API_KEY"],
base_url="https://api.apiyi.com/v1" # OpenAI-совместимый интерфейс APIYI
)
MODEL = "your-model-name" # уточняйте по списку моделей на платформе
search_tool = {"type": "function", "function": {
"name": "search_tool_registry",
"description": "Search internal business tools by keyword.",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}
Посмотреть полный двухэтапный вызов собственного Tool Registry
import json, os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIYI_API_KEY"],
base_url="https://api.apiyi.com/v1"
)
MODEL = "your-model-name" # ориентируйтесь на список моделей платформы
TOOL_REGISTRY = {
"get_inventory": {"type": "function", "function": {
"name": "get_inventory",
"description": "Retrieve the available inventory for a product SKU.",
"parameters": {"type": "object", "properties": {"sku": {"type": "string"}}, "required": ["sku"]}}},
"get_order_status": {"type": "function", "function": {
"name": "get_order_status",
"description": "Retrieve the status of a customer order.",
"parameters": {"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]}}},
}
search_tool = {"type": "function", "function": {
"name": "search_tool_registry",
"description": "Search internal business tools (inventory, orders) by keyword.",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}
def search_registry(query):
q = query.lower()
return [name for name, t in TOOL_REGISTRY.items()
if any(w in t["function"]["description"].lower() for w in q.split())]
def execute_demo_tool(name, args):
if name == "get_inventory":
return {"sku": args["sku"], "available": 12, "data_source": "local_demo"}
if name == "get_order_status":
return {"order_id": args["order_id"], "status": "demo_pending", "data_source": "local_demo"}
raise ValueError(name)
messages = [{"role": "user", "content": "查询商品 SKU-42 的可用库存。"}]
tools = [search_tool]
for _ in range(4): # простой лимит итераций, чтобы не уйти в бесконечный цикл
resp = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
msg = resp.choices[0].message
if not msg.tool_calls:
print("最终回答:", msg.content)
break
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
if call.function.name == "search_tool_registry":
names = search_registry(args["query"])
tools += [TOOL_REGISTRY[n] for n in names if TOOL_REGISTRY[n] not in tools]
content = json.dumps({"loaded_tools": names})
else:
content = json.dumps(execute_demo_tool(call.function.name, args), ensure_ascii=False)
messages.append({"role": "tool", "tool_call_id": call.id, "content": content})
💡 Как выбрать: качество поиска на маршруте с реестром полностью зависит от вашей функции поиска — совпадение по ключевым словам в примере нужно только для демонстрации. Переключайте модели на APIYI apiyi.com и прогоняйте один и тот же набор задач: сравнивайте, «нашёлся ли нужный инструмент» и «правильно ли заполнены параметры» — так сразу видно, какая модель лучше подходит для вашей библиотеки инструментов.
Gemini Tool Retrieval: разбор типичных ошибок
| Симптом | Причина | Решение |
|---|---|---|
defer_loading requires tool_search |
объявлена отложенная функция, но нет серверного tool_search |
добавьте в tools элемент {"type": "tool_search"} |
short_description невалиден |
указан у функции без отложенной загрузки | используйте только для функций с defer_loading=True |
| HTTP 400 unsupported model | модели нет в списке поддерживаемых | используйте один из 4 ID моделей из документации |
| Запрос не выполняется или выдаёт ошибку версии | SDK по умолчанию использует v1 или вызывается generateContent |
явно задайте api_version="v1beta" и перейдите на Interactions API |
| HTTP 400 на втором раунде | при store=False пропущен шаг поиска или signature |
дословно воспроизведите tool_search_call/result и все signature |
| Модель использует старые инструменты или инструменты недоступны | в последующих запросах не передан tools |
каждый раз заново отправляйте полный массив tools |
| После поиска параметры пусты | для отложенного инструмента передан только name и краткое описание |
даже для отложенного инструмента отправляйте полные parameters |
| Не удаётся настроить клиентский поиск | не хватает полей name, description и т. п. |
допишите определение клиентской функции поиска |
Режим без состояния (store=False) требует отдельного пояснения. В этом случае нельзя полагаться на previous_interaction_id: приложение должно само сохранять и дословно воспроизводить пользовательский ввод, tool_search_call, tool_search_result, function_call, function_result, а также все signature. Если удалить или изменить хотя бы один шаг, сервер может не восстановить контекст поиска. Кроме того, если сервер не нашёл подходящих инструментов, он может вернуть просто текст, а не структурированную ошибку. Поэтому «запрос не упал» ≠ «поиск удался»: при проверке нужно по пунктам смотреть, появились ли в steps ожидаемые шаги поиска и вызовы функций.
Анализ Gemini Tool Retrieval: когда стоит подключать
Вывод 1: выгода зависит от размера библиотеки инструментов и длины контекста, а не от самого факта включения. В документации Google приведены два гипотетических примера расчёта с противоположными результатами, и прямо сказано, что это не производственный бенчмарк. Первый: 200 инструментов по 400 токенов, базовый контекст 2 000 токенов, 2 запроса — при статической загрузке получается примерно 164 000 токенов, при Tool Retrieval около 23 650, то есть снижение примерно на 85,6%. Второй: 10 инструментов и базовый контекст 30 000 токенов — статическая загрузка даёт 68 000 токенов, а Tool Retrieval, наоборот, 92 830 токенов, то есть рост примерно на 36,5%: дополнительный поисковый вывод вынужден заново обрабатывать весь длинный контекст. Инженерная рекомендация Google такова: если стабильных инструментов меньше примерно 20, статической загрузки обычно достаточно.

Вывод 2: при оценке затрат нужно смотреть на total_tool_use_tokens, а не только на входные токены первого раунда. В ранних официальных тестах краткое описание каждого отложенного инструмента занимало в среднем около 26 токенов; для 100 инструментов это примерно 2 600 токенов, и это приблизительная цифра. Реально следить стоит за дополнительными вызовами модели, которые провоцирует поиск, и за накоплением уже загруженных Schema в рамках сессии. В текущей документации нет механизма выгрузки уже найденных инструментов: чем больше инструментов найдено в длинной сессии, тем больше контекст. Кэш тоже не даёт безусловной выгоды: после сокращения начального промпта он может оказаться ниже минимального порога неявного кэширования.
Вывод 3: загрузка инструментов по требованию уже стала отраслевым консенсусом, но данные разных вендоров нельзя переносить друг на друга. Anthropic выпустила Tool Search Tool в ноябре 2025 года, OpenAI в марте 2026 года представила Tool Search вместе с GPT-5.4 — обе компании публиковали измеренную экономию в своих условиях. Google же на этот раз дала только гипотетические примеры расчёта. По состоянию на 20 ноября 2026 года независимых производственных замеров Gemini Tool Retrieval, которые можно было бы проверить, не существует. Поэтому утверждения вроде «Gemini на практике экономит 85%» сейчас не выдерживают критики.
Рекомендации разработчикам: сначала разложите инструменты существующего Agent по частоте вызовов — часто используемые загружайте напрямую, а редкие из длинного хвоста загружайте лениво. Затем на одном и том же наборе задач сравните статическую загрузку и Tool Retrieval по общему числу токенов, сквозному времени выполнения, доле правильного выбора инструмента и точности аргументов. Функция всё ещё находится в статусе превью, дата официального релиза не определена, поэтому в продакшене лучше держать переключатель для откатa к статической загрузке. На этапе выбора модели можно сначала недорого прогнать стандартный baseline Function Calling через единый интерфейс APIYI apiyi.com, а затем перейти на официальный v1beta, чтобы проверить чистую выгоду Tool Retrieval.
Чем больше инструментов, тем важнее заранее продумать, когда какой из них доставать. Как сказано в «Лунь юй», глава «Вэй Лин-гун»: «Мастер, желающий сделать дело хорошо, должен сначала отточить свои инструменты».
📚 Справочные материалы
-
Introducing Tool Retrieval in the Gemini API: официальный анонс Google
- Ссылка:
blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval - Описание: дата публикации, цели дизайна, MCP и два режима извлечения
- Ссылка:
-
Официальная документация Tool Retrieval: конфигурация, ограничения, тарификация и примеры расчётов
- Ссылка:
aistudio.google.com/docs/tool-retrieval - Описание: основной источник для кода из этой статьи, правил обработки ошибок, воспроизведения без сохранения состояния и примеров расчёта токенов
- Ссылка:
-
Официальная документация Function Calling: выполнение функций и возврат результатов
- Ссылка:
aistudio.google.com/docs/function-calling - Описание: стандартное использование
function_resultиcall_id
- Ссылка:
-
Официальная документация Interactions API: структура интерфейса и шаги выполнения
- Ссылка:
aistudio.google.com/docs/interactions-overview - Описание: диалог с сохранением состояния, а также различия между steps и generateContent
- Ссылка:
-
Release python-genai v3.6.0 / v3.0.0: история версий SDK
- Ссылка:
github.com/googleapis/python-genai/releases - Описание: поддержка схемы Tool Retrieval и изменения версии API по умолчанию
- Ссылка:
Автор: техническая команда APIYI
Технические консультации: для сравнительного тестирования Function Calling на нескольких моделях заходите на APIYI apiyi.com; больше материалов по интеграции — в центре документации docs.apiyi.com
