Skill служит инструкцией для агента, а не слоем управления production-системой
В репозитории Google Gemini опубликован skill gemini-interactions-api для coding agents. Такой файл не создаёт новый runtime и не выдаёт приложению доступы. Его задача практичнее: направить агента-разработчика к документации и примерам по Gemini Interactions API.
Существенен не формат SKILL.md, а подход к разработке. Вместо схемы «отправили промпт, получили текст» Interactions API предлагает работать с объектом Interaction, последовательностью шагов, встроенными и собственными инструментами, серверным состоянием и фоновым исполнением. Интеграция становится наблюдаемее, однако ответственность за права, данные, ошибки и действия во внешних системах остаётся на стороне приложения.
SKILL.md описывает работу с Interactions API на Python и JavaScript/TypeScript. В нём охвачены генерация, многоходовые сценарии, streaming, function calling, структурированный вывод, File Search и миграция со старого подхода generateContent. Документ должен дать coding agent маршрут к актуальным материалам и примерам, а не заменить официальную документацию или эксплуатационные процедуры команды.
В дискуссии о skills это различие легко упустить. Инструкция, которую читает агент, влияет на предлагаемый им код: выбор endpoint, сущностей и паттернов. После генерации перед командой остаётся обычный код приложения. Его необходимо проверить на code review, запустить в тестовом проекте, сверить с API reference и сопровождать как любую интеграцию с внешним сервисом.
Репозиторий отдельно предупреждает, что skills не являются официально поддерживаемым продуктом Google. Их нельзя считать договорным слоем enterprise-поддержки, механизмом выдачи прав или гарантией совместимости. В production контроль определяется настройками проекта, способом хранения секретов, серверной политикой инструментов, журналами событий, лимитами и тестами.
Для команды вывод прост. Skill полезен на этапе разработки, особенно при быстро меняющемся API. Однако он не может быть окончательным источником решения. Версию SDK, модель, версию API и доступные tools следует явно фиксировать в коде и конфигурации, а не оставлять их неявным следствием подсказки агенту.
- Используйте skill как навигатор по документации для coding agent, а не как средство безопасности.
- Проверяйте сгенерированный код по официальному reference перед релизом.
- Фиксируйте версию SDK, модель, версию API и разрешённые tools в репозитории.
- Не считайте обновление GitHub-файла запуском отдельного enterprise-продукта.
Цитата в переводе«Не является официально поддерживаемым продуктом Google.»
Interaction превращает ответ модели в наблюдаемый сценарий
Interactions API строится вокруг объекта Interaction. Он содержит хронологическую последовательность steps: пользовательский ввод, ответ модели, запрос функции, результат функции и события встроенных инструментов. Поэтому API подходит не только для получения финального текста, но и для сценариев, в которых модель проходит несколько этапов выполнения.
В привычной stateless-схеме приложение каждый раз само собирает контекст: историю диалога, системные инструкции, сведения об инструментах и результаты предыдущих вызовов. В Interactions API новый ход можно связать с предыдущим через previous_interaction_id. Это сокращает необходимость повторно отправлять всю историю, но требует осознанно решить, нужно ли приложению серверное состояние и как оно соотносится с политикой данных.
Продолжение истории не означает автоматический перенос полномочий. Tools, system_instruction и generation configuration необходимо вновь задавать для каждого нового interaction. Для production это полезная граница: контекст диалога можно сохранить, но допустимые действия следует определять заново на каждом ходе.
API поддерживает фоновое выполнение через background=true: приложение получает идентификатор interaction, а затем отслеживает его состояние отдельными запросами, streaming или webhook-механизмом. Режим подходит для длительных задач, но добавляет типичные требования распределённой системы: обработку статусов, дедупликацию, таймауты и понятный пользовательский сценарий для незавершённой операции.
Наблюдаемость не равна доказательству качества. Последовательность шагов помогает выяснить, что произошло: модель запросила функцию, backend вернул ошибку или политика заблокировала действие. Однако журнал сам по себе не делает вывод модели верным. Проверка результата по-прежнему зависит от задачи, источников данных и правил продукта.
- Рассматривайте Interaction как объект выполнения задачи, а не как увеличенное чат-сообщение.
- Сохраняйте в собственном журнале interaction.id, время вызова, версию конфигурации и технический идентификатор пользователя.
- Формируйте список tools для каждого хода в серверной политике.
- Для background-сценариев заранее проектируйте polling, webhook-приёмник и обработку зависших задач.
GA API не гарантирует стабильность каждой функции в его составе
Google рекомендует Interactions API для новых проектов и описывает его как общедоступный интерфейс. Этого достаточно, чтобы рассматривать API как базовый вариант для нового кода. Однако статус API нельзя автоматически распространять на каждую модель, встроенный инструмент или режим, доступный в том же developer surface.
В документации и changelog могут одновременно присутствовать стабильные и preview-возможности. Для команды это вопрос архитектуры, а не терминологии: экспериментальный маршрут не следует без отдельной оценки превращать в единственную основу критичного процесса. Его разумно изолировать feature flag, отдельно измерять ошибки и предусмотреть конфигурацию отката на разрешённый вариант.
Ошибки также возникают из-за версий endpoint и примеров миграции. В reference и практических материалах могут использоваться разные варианты API, включая v1beta. Рабочий URL, модель и формат полей нельзя определять по случайному фрагменту кода. Их необходимо сверять с reference на дату релиза и подтверждать smoke-тестом в проекте, где будет работать сервис.
То же относится к содержимому skill. Его ценность в том, что он направляет к свежим источникам, но репозиторий, SDK и документация обновляются не обязательно синхронно. Пример надёжнее считать отправной точкой, чем доказательством доступности модели или функции в конкретном аккаунте.
- GA для API не означает одинаковый жизненный цикл всех моделей и tools.
- Не копируйте endpoint и строку модели из старого примера без сверки с reference.
- Держите preview-функции за feature flag и отдельно проверяйте их при обновлениях.
- Указывайте в логах production-вызова модель и версию API.
Цитата в переводе«Общедоступен.»
File Search требует отдельного жизненного цикла поисковых данных
File Search в Gemini API точнее рассматривать как встроенный RAG-механизм, то есть генерацию с дополнением найденным контекстом. Сервис импортирует и индексирует материалы, ищет семантически близкие фрагменты, затем использует найденный контекст при генерации. Это отличается от разовой передачи файла в запрос: у поиска появляются собственное хранилище, операции и вопросы управления данными.
Документация описывает текстовый поиск с gemini-embedding-001, а для изображений и мультимодального поиска использует gemini-embedding-2. Аудио и видео в File Search пока не поддерживаются. Поэтому продуктовый интерфейс не должен обещать одинаковую поисковую функциональность для любого загруженного пользователем материала. Тип данных следует учитывать до индексации.
Особого внимания требует различие между исходным File и FileSearchStore. По документации, исходный файл удаляется через 48 часов, тогда как эмбеддинги в store сохраняются до ручного удаления либо до прекращения поддержки использованной модели. Следовательно, удаление оригинала не удаляет автоматически поисковое представление документа.
Ответ может содержать file_citation, номера страниц или идентификаторы фрагментов. Это позволяет показать пользователю происхождение контекста и быстрее проверить ответ. Однако citation подтверждает, какой фрагмент был использован, а не правильность вывода модели. В чувствительных сценариях ссылка должна служить основанием для проверки человеком, а не заменять её.
Поэтому для File Search нужна отдельная политика: кто загружает данные, какие документы разрешено индексировать, в какой store они попадают, кто может их удалять и как citations обрабатываются в интерфейсе. Иначе удобство RAG будет сопровождаться непрозрачным расширением поверхности управления данными.
- Включайте удаление FileSearchStore в retention-процедуры, а не ограничивайтесь удалением исходного файла.
- Разделяйте stores по клиентам, проектам или классам данных, если этого требует ваша модель доступа.
- Показывайте citations пользователю, но не называйте ответ автоматически проверенным.
- Тестируйте отдельно качество поиска и качество итоговой генерации.
Инструменты: модель предлагает действие, backend принимает решение
Interactions API поддерживает function calling и встроенные инструменты. Это не даёт оснований предоставлять модели прямой доступ к CRM, платежам, внутренним базам или административным операциям. Безопасная граница устроена иначе: модель формирует предложение function_call, а доверенный backend проверяет допустимость действия, валидность аргументов и право пользователя на его выполнение.
Первый уровень контроля представляет собой allowlist, то есть явный список разрешённых функций. Каждая функция должна быть зарегистрирована явно, иметь ограниченную JSON-схему входных данных и предсказуемый формат результата. Поле, сгенерированное моделью, не должно становиться именем произвольного внутреннего метода. Аргументы следует валидировать до исполнения, а данные от внешнего инструмента считать данными, которые модель может неверно интерпретировать.
Для операций записи нужны дополнительные продуктовые барьеры. В зависимости от риска это могут быть идемпотентность, лимиты, проверка полномочий на стороне приложения и явное подтверждение человека. Это не встроенная гарантия API, а инженерное следствие архитектуры tool use: если ошибка меняет данные или приводит к финансовому действию, одного текста, сгенерированного моделью, недостаточно для авторизации.
Такая прослойка полезна и в эксплуатации. В журнале можно последовательно увидеть исходный запрос, набор разрешённых tools, предложенный вызов, результат валидации, решение policy layer, ответ внешней системы и финальный ответ модели. Это помогает отличить галлюцинацию от ошибки исходных данных, а проблему прав от отказа внешнего сервиса.
- Не предоставляйте модели универсальный административный tool.
- Валидируйте JSON-аргументы до вызова внешней системы и фиксируйте результат проверки.
- Для рискованных мутаций используйте идемпотентность, лимиты и при необходимости human approval.
- Выдавайте инструментам отдельные сервисные учётные данные с минимально необходимыми правами.
Ошибки доступа и квот требуют разной реакции
Ошибки аутентификации, доступа и квоты могут выглядеть похожими на общей панели мониторинга, но относятся к разным классам проблем. Единый автоматический retry для 401, 403 и 429 не устраняет первопричину, а при лимитах способен увеличить нагрузку. Обработку ошибок следует проектировать по смыслу статуса, а не только по факту неуспешного ответа.
Код 401 указывает на проблему аутентификации: ключ может отсутствовать, быть недействительным или передаваться в runtime не так, как ожидает клиент. Проверять нужно источник секрета, переменные окружения и конфигурацию деплоя. Повтор идентичного запроса без изменения этих условий обычно не решает проблему.
Код 403 означает отказ в доступе. Причина может быть связана с ограничениями ключа, правами проекта, организационными настройками или доступностью ресурса. Здесь требуется проверить разрешения и конфигурацию проекта, а не повторно отправлять тот же вызов.
Для 429 важна многомерность лимитов. Gemini API учитывает, в частности, requests per minute, input tokens per minute и requests per day; превышение любой из этих величин может вызвать отказ. Поэтому запас квоты нельзя оценивать только по числу запросов: большой контекст способен исчерпать лимит токенов даже при умеренной частоте обращений. Лимиты также зависят от модели и usage tier.
Для 429 и временных 5xx уместен ограниченный exponential backoff с jitter. Увеличивающаяся пауза снижает давление на сервис, а случайный разброс не позволяет множеству воркеров одновременно создать новую волну повторов. Для 400 и 403 этот механизм не исправляет проблему: сначала необходимо изменить запрос или права.
При streaming ошибка может прийти уже в SSE-потоке, а не только до начала ответа. Клиент должен корректно завершить пользовательский сценарий, сохранить технический контекст и не представить частичный текст как завершённый результат.
- Для 401 проверяйте секрет, передачу ключа и настройки runtime.
- Для 403 проверяйте права, ограничения проекта и доступность ресурса, не ретрайте вслепую.
- Для 429 измеряйте RPM, TPM и дневное потребление, используйте ограниченный backoff с jitter.
- Для 5xx задайте лимит повторов и заранее определённый fallback.
- Логируйте SSE-ошибки так же подробно, как обычные HTTP-ответы.
Серверное состояние удобно, но требует решения о хранении данных
previous_interaction_id и фоновое выполнение упрощают многоходовые и длительные сценарии, но зависят от серверного хранения. В документации указано, что Interactions API использует store=true по умолчанию. Выбор stateful-подхода должен учитывать не только удобство разработки, но и состав данных, передаваемых в модель, а также допустимый срок их нахождения в этом контуре.
Для платного tier interactions хранятся 55 дней, для free tier один день; в AI Studio для платных проектов доступны окна удаления логов в 7, 14, 28 или 55 дней. Эти параметры относятся к описанному механизму API, но не заменяют внутреннюю политику хранения, юридическую оценку данных и проверку актуальных условий перед запуском.
При store=false серверное сохранение состояния отключается, но одновременно становятся недоступны previous_interaction_id и background=true. Это полноценный архитектурный компромисс. Stateless-подход уменьшает зависимость от серверной истории, однако приложение должно самостоятельно управлять контекстом и не может использовать stateful-механизмы API.
Связка Interactions и File Search требует особенно аккуратной модели retention. История interaction и поисковые представления файлов являются разными сущностями с разными правилами жизненного цикла. Политика удаления должна охватывать оба контура, а в API следует передавать только контекст, необходимый для текущего шага.
- Выберите store=true или store=false до проектирования UX многоходового диалога.
- Сопоставьте retention Interactions и File Search с общей политикой удаления данных.
- Минимизируйте объём контекста, передаваемого для конкретной задачи.
- Проверяйте актуальные условия хранения и доступные настройки до production-запуска.
Минимально зрелый контур: контракт, политика, тесты и наблюдаемость
Зрелая интеграция начинается с контракта, а не с эффектного демо. Команде следует определить, какие задачи разрешены модели, какие данные допустимы, какие инструменты доступны, где требуется подтверждение пользователя и что произойдёт при отказе API или внешней системы. Interactions API даёт удобный материал для наблюдаемости через структуру шагов, но не заменяет собственный policy layer.
Практический минимум включает smoke-test interactions.create с закреплённой моделью и минимальной конфигурацией в том же проекте, где будет работать сервис. Затем потребуются отдельные тесты каждого разрешённого инструмента и контрактные проверки форматов запросов и ответов. При обновлении SDK, модели или версии API такие проверки помогают обнаружить несовместимость до релиза.
Эксплуатационные метрики должны связывать поведение модели с реальными ограничениями системы: долю 401, 403, 429 и 5xx, задержки по типам задач, объём входных токенов, успешность tool calls и долю вызовов, отклонённых policy layer. Эти показатели полезнее абстрактной оценки качества чата, поскольку показывают, где интеграция теряет доступность, деньги или управляемость.
Для простого одноразового ответа такая архитектура может показаться избыточной. Это справедливо, если приложение не работает с закрытыми данными, не вызывает внешние системы и не требует многоходового состояния. Но когда модель получает инструменты, документы или возможность инициировать действие, отсутствие границ быстро обходится дороже базового policy layer и журналирования.
- Запускайте контрактный smoke-test при каждом деплое и обновлении SDK.
- Сделайте allowlist моделей и tools частью конфигурации, проверяемой в code review.
- Собирайте аудит по interaction.id, шагам, policy decision и кодам ошибок.
- Отделяйте метрики доступности API от метрик качества продукта.
- Готовьте fallback для перегрузки, недоступности модели и отказа внешнего инструмента.
Что это означает на практике
Gemini Skills следует воспринимать трезво: это способ помочь coding agent найти релевантные первоисточники, а не новый слой корпоративного управления. Значение skill становится заметным по мере усложнения интеграции с моделью: появляются состояние, шаги, инструменты, поиск по файлам, доступы и квоты.
Interactions API даёт подходящую модель для таких сценариев. Interaction можно продолжать, наблюдать, связывать с инструментами и выполнять в фоне. Но API показывает траекторию выполнения, а ответственность за допустимость действия остаётся у приложения. Production-готовность определяется тем, способна ли команда ограничить доступы, объяснить хранение данных, обработать ошибки и провести каждый tool call через контролируемую серверную границу.
- Используйте Gemini Skills для навигации coding agent по документации, но не считайте skill механизмом контроля runtime.
- Для нового кода оценивайте Interactions API как базовый интерфейс, закрепляя модель, версию API и набор tools в конфигурации.
- Ставьте серверный policy layer между моделью и бизнес-системами: allowlist функций, валидация JSON, минимальные права и подтверждение рискованных действий.
- Проектируйте File Search как отдельный жизненный цикл данных: индексирование, доступ к store, citations и удаление поисковых представлений.
- Не смешивайте обработку ошибок: 401 и 403 требуют исправления аутентификации или прав, 429 и временные 5xx требуют ограниченных повторов с backoff и jitter.
- До запуска stateful-сценария определите retention-политику: store=false отключает серверное состояние, но лишает previous_interaction_id и background execution.
Чек-лист перед production-запуском
Сохраните памятку в PDF и используйте её как основу для технической приёмки интеграции. Чек-лист не заменяет требования безопасности и хранения данных, принятые в конкретной организации.
Контракт и конфигурация
Зафиксируйте технический контракт до того, как coding agent или команда начнут расширять сценарий новыми tools.
- Закреплены используемые модель, SDK и версия API.
- В конфигурации определён allowlist разрешённых моделей и tools.
- Для preview-возможностей предусмотрены feature flag и вариант отката.
- Smoke-test запускается в том же проекте, где будет работать сервис.
Данные и File Search
Отдельно проверьте жизненный цикл исходных файлов, поисковых представлений и истории interaction.
- Определено, какие документы допустимо индексировать.
- Stores разделены в соответствии с моделью доступа.
- Удаление FileSearchStore включено в retention-процедуры.
- В интерфейсе citations показываются как основание для проверки, а не как автоматическое подтверждение корректности ответа.
- Передаваемый на каждом шаге контекст ограничен необходимым минимумом.
Инструменты, права и эксплуатация
Убедитесь, что предложение действия от модели не становится прямым разрешением на действие во внешней системе.
- JSON-аргументы tool call валидируются до исполнения.
- Для рискованных операций определены идемпотентность, лимиты и при необходимости human approval.
- Сервисные учётные данные инструментов имеют минимально необходимые права.
- В аудит записываются interaction.id, шаги, policy decision и коды ошибок.
- Для 401, 403, 429, 5xx и ошибок streaming предусмотрены разные сценарии обработки.
Источники
Частые вопросы
Что такое Gemini Skills?
Gemini Skills — это открытые инструкции для coding agents, которые направляют их к документации и примерам Gemini API. Skill не создаёт runtime, не выдаёт доступы и не заменяет production-архитектуру.
Чем Interactions API отличается от обычного запроса к модели?
Interactions API строится вокруг объекта Interaction и последовательности steps. В ней можно проследить пользовательский ввод, ответ модели, вызовы функций, результаты инструментов и продолжение сценария через previous_interaction_id.
Зачем нужен policy layer при function calling?
Модель только предлагает function_call. Доверенный backend должен проверить allowlist функции, JSON-аргументы, полномочия пользователя, ограничения операции и необходимость подтверждения человеком.
Удаляется ли поисковое представление после удаления файла в File Search?
Нет, удаление исходного File не означает автоматического удаления эмбеддингов в FileSearchStore. Политика retention должна учитывать оба объекта.
Что теряется при store=false в Interactions API?
При store=false отключается серверное сохранение состояния. Одновременно недоступны previous_interaction_id и background=true, поэтому приложению придётся самостоятельно управлять контекстом.
Можно ли одинаково ретраить ошибки 401, 403 и 429?
Нет. 401 требует проверки аутентификации и секрета, 403: прав и конфигурации проекта. Для 429 уместны измерение лимитов и ограниченный backoff с jitter.
Практический чек-лист
Чек-лист: Gemini Interactions API перед production-запуском
Данные ниже предназначены для локальной сборки downloads/gemini-interactions-api-production-checklist.pdf и одной строки листа Downloads: filename: gemini-interactions-api-production-checklist.pdf; title: «Чек-лист Gemini Interactions API перед production-запуском»; description: «Памятка по контракту, инструментам, данным File Search, состоянию и обработке ошибок»; buttonLabel: «Скачать PDF».
Контракт и конфигурация
- Закреплены используемые модель, SDK и версия API.
- В конфигурации определён allowlist разрешённых моделей и tools.
- Для preview-возможностей предусмотрены feature flag и вариант отката.
- Smoke-test запускается в том же проекте, где будет работать сервис.
Данные и File Search
- Определено, какие документы допустимо индексировать.
- Stores разделены в соответствии с моделью доступа.
- Удаление FileSearchStore включено в retention-процедуры.
- В интерфейсе citations показываются как основание для проверки, а не как автоматическое подтверждение корректности ответа.
- Передаваемый на каждом шаге контекст ограничен необходимым минимумом.
Инструменты, права и эксплуатация
- JSON-аргументы tool call валидируются до исполнения.
- Для рискованных операций определены идемпотентность, лимиты и при необходимости human approval.
- Сервисные учётные данные инструментов имеют минимально необходимые права.
- В аудит записываются interaction.id, шаги, policy decision и коды ошибок.
- Для 401, 403, 429, 5xx и ошибок streaming предусмотрены разные сценарии обработки.
Вопросы и ответы
Что такое Gemini Skills?
Gemini Skills — это открытые инструкции для coding agents, которые направляют их к документации и примерам Gemini API. Skill не создаёт runtime, не выдаёт доступы и не заменяет production-архитектуру.
Чем Interactions API отличается от обычного запроса к модели?
Interactions API строится вокруг объекта Interaction и последовательности steps. В ней можно проследить пользовательский ввод, ответ модели, вызовы функций, результаты инструментов и продолжение сценария через previous_interaction_id.
Зачем нужен policy layer при function calling?
Модель только предлагает function_call. Доверенный backend должен проверить allowlist функции, JSON-аргументы, полномочия пользователя, ограничения операции и необходимость подтверждения человеком.
Удаляется ли поисковое представление после удаления файла в File Search?
Нет, удаление исходного File не означает автоматического удаления эмбеддингов в FileSearchStore. Политика retention должна учитывать оба объекта.
Что теряется при store=false в Interactions API?
При store=false отключается серверное сохранение состояния. Одновременно недоступны previous_interaction_id и background=true, поэтому приложению придётся самостоятельно управлять контекстом.
Можно ли одинаково ретраить ошибки 401, 403 и 429?
Нет. 401 требует проверки аутентификации и секрета, 403 — прав и конфигурации проекта. Для 429 уместны измерение лимитов и ограниченный backoff с jitter.
