gemini-interactions-api

Официальный навык Google объясняет Gemini Interactions API на Gemini Enterprise Agent Platform как stateful, server-managed интерфейс для многошаговых взаимодействий с агентом. Он полезен для multi-turn диалогов, фонового выполнения, потоковой выдачи, структурированного результата и function calling, когда состояние взаимодействия и последовательность шагов важнее простого одноразового вызова модели. В руководстве показаны Python и TypeScript/JavaScript варианты, а также REST-подход для shell-скриптов и сред, где SDK не используется. Перед запуском нужно настроить Application Default Credentials и включить aiplatform.googleapis.com. Рекомендуемый клиент — Google Gen AI SDK: для Python и JavaScript/TypeScript в тексте навыка указана поддерживаемая граница google-genai или @google/genai версии 2.3.0 и выше. Старые пакеты google-cloud-aiplatform, @google-cloud/vertexai и google-generativeai для Interactions не поддерживаются, поэтому перенос кода с этих библиотек нельзя считать механической заменой импорта. В конфигурации через окружение используются GOOGLE_GENAI_USE_ENTERPRISE=true, GOOGLE_CLOUD_PROJECT и GOOGLE_CLOUD_LOCATION; возможен и явный enterprise-конфиг клиента. Ключевое ограничение зависит от GEAP: вызов должен адресовать provisioned agent или endpoint через параметр agent. Прямой вызов базовой модели через model=... на Agent Platform в описанном сценарии не поддерживается, даже если похожий параметр встречается в документации другого Gemini API. Навык также предупреждает, что перечисленные legacy-модели вроде gemini-2.5-*, gemini-2.0-* и gemini-1.5-* устарели и не поддерживают Interactions API; актуальный выбор нужно перепроверять по официальной документации миграции моделей. В карточке перечислены gemini-3.5-flash, gemini-3.1-pro-preview и gemini-3.1-flash-lite как варианты для разных профилей скорости, рассуждения и стоимости, но это не заменяет текущую проверку доступности. Одноразовый запрос создаётся через interactions.create с agent и input, а результат удобно читать через output_text. Для продолжения диалога сохраняется id предыдущего взаимодействия и передаётся previous_interaction_id; состояние хранится на сервере по умолчанию. store=false отключает хранение и вместе с ним previous_interaction_id и background, поэтому режим хранения нужно выбирать осознанно. Для real-time выдачи включается stream=true: клиент получает последовательность событий interaction.created, step.start, step.delta, step.stop и interaction.completed, а REST-ответ работает как Server-Sent Events с chunked-потоком. Structured output задаётся через response_format и схему, например Pydantic-модель, чтобы получить типизированный JSON. Function calling строится вокруг локального инструмента: первый запрос передаёт tools, затем приложение обрабатывает top-level шаг function_call и возвращает результат с call_id в продолжение того же interaction. Важная деталь схемы — у function_call плоские поля name и arguments, а не вложенный список tool_calls. Параметры tools, system_instruction и generation_config являются turn-scoped и должны передаваться на каждом нужном запросе, включая продолжение после tool call. Карточка полезна как практический каркас интеграции, но не обещает доступность проекта, роли, provisioned agent или конкретной модели. Нужно отдельно проверить IAM, регион, лимиты, retention и текущую схему SDK; секреты и идентификаторы нельзя печатать в логи. REST-примеры подходят для отладки и простых скриптов, однако потоковые и многошаговые сценарии требуют обработки ошибок, остановки при незавершённом interaction и контроля стоимости. Сам навык фиксирует ограничения платформы и рекомендуемый протокол, а не является security-аудитом или гарантией результата бизнес-агента.