11 октября 2026 г.
Genkit Dart 1.0: как добавить ИИ в приложение Flutter

Genkit Dart 1.0 - стабильный набор инструментов Google для ИИ-функций в приложениях на Dart и Flutter. Он связывает вызов модели, проверяемый формат ответа, инструменты и журнал выполнения в один рабочий процесс. Для первого проекта держи модель и секретный ключ на сервере, а Flutter подключай к нему по HTTP. Пакет уже опубликован, но расширенный API постоянных агентов пока в бете.
Повод свежий: команда Flutter объявила о версии 1.0 8 октября. Я бы не бросался сразу собирать «автономного сотрудника». Интереснее посмотреть на скучную, но нужную часть: как отправить запрос из приложения, получить структурированный результат и увидеть, где модель ошиблась или зачем вызвала инструмент.
Что именно вышло, а что ещё эксперимент
Genkit - открытый фреймворк для ИИ-функций. Его ядро умеет вызывать модели, описывать шаги обработки как flows, проверять ввод и вывод по схеме, отдавать результат клиенту и показывать трассу исполнения. В Dart теперь есть стабильный релиз 1.0.0. Карточка пакета на pub.dev подтверждает версию и требование Dart SDK 3.12. Если у тебя Dart старее, сначала обнови SDK: в некоторых страницах учебника ещё написано «3.10», но актуальный пакет 1.0.0 требует 3.12. Я бы здесь доверял метаданным самого пакета.
Важная оговорка к слову «стабильный»: стабильным стал основной SDK. API долгоживущих агентов с историей диалога, состоянием и возобновлением работы официальная документация по-прежнему называет Beta. Его импорты вынесены в package:genkit/experimental.dart; при минорных обновлениях там возможны несовместимые изменения. Если ты собираешь продукт для клиентов, обычного flow для генерации или обработки запроса часто достаточно. Агент нужен, когда без длинной беседы, шагов с инструментами и сохранения состояния задача действительно не складывается.
Как работает связка Flutter и ИИ
Представь приложение, которое собирает рецепт из того, что есть дома. Экран Flutter принимает список продуктов. Серверный flow проверяет запрос, спрашивает модель, при необходимости вызывает функцию с ценами или остатками и возвращает результат по полям: название, ингредиенты, шаги. Flutter показывает их постепенно. Это пример Bargain Chef из официального учебника, там инструмент читает демонстрационные скидки, а не настоящую базу магазина. Механика важнее рецепта: ты видишь границу между твоими данными, решением модели и кодом, который вообще имеет право что-то сделать.

На стороне сервера Genkit упаковывает логику в defineFlow: у функции есть входная и выходная схемы, сама генерация и трасса вызовов. Отдельный GenkitRouter публикует flow через HTTP. Клиент Flutter обращается к этому адресу, а не хранит ключ к Gemini или Claude в коде экрана. Если модель вернула куски структурированного ответа, приложение может показывать готовые поля, пока остальные ещё формируются. Но схема не делает содержание правдивым: если модель указала несуществующую скидку, формат JSON будет правильным, а цена - нет. Поэтому инструмент с данными и последняя проверка правил остаются твоей работой.
Есть и другие варианты размещения. Google описывает прямой вызов модели из Flutter для прототипа или сценария, где пользователь вводит собственный ключ. А для выпуска публичного приложения предлагает сервер или промежуточный бэкенд с авторизацией. В браузерной сборке Flutter отдельный сервер обязателен для этого flow. На телефоне клиентская интеграция технически возможна, но секрет, зашитый в распространяемый пакет, перестаёт быть секретом. Мой выбор для рабочего продукта - серверная граница с учётом пользователей и лимитов.
Как попробовать без большого проекта
Официальный стартовый маршрут для Dart начинается с консольного приложения на Shelf. Нужны установленные Dart SDK подходящей версии, ключ к Gemini API и отдельный терминал для бэкенда. Сначала создаёшь проект командой dart create -t console my_genkit_shelf, заходишь в папку и добавляешь зависимости:
dart pub add genkit genkit_google_genai genkit_shelf schemantic shelf shelf_router dev:build_runner
Здесь genkit отвечает за основную логику, genkit_google_genai подключает Gemini, genkit_shelf публикует flow через Shelf, а schemantic вместе с build_runner генерирует схемы для типизированного ответа. Это список из официальной инструкции для Shelf, не результат запуска на моём компьютере. Если предпочитаешь Claude или OpenAI, у Genkit есть отдельные плагины провайдеров; установка одного ядра genkit сама по себе не выдаёт доступа к платной модели.
Ключ задаётся переменной GEMINI_API_KEY в окружении сервера. Подставь свой ключ локально, но не копируй его в статью, репозиторий, скриншот или Flutter-клиент. Код бэкенда по руководству создаёт flow bargainChefFlow, где есть схема ответа, вызов Gemini и функция поиска демонстрационных цен. После добавления кода запускаешь dart run build_runner build, затем dart run. Ожидаемый адрес сервера в учебнике - http://localhost:8080. Если запуск падает на отсутствующей схеме, сначала проверь шаг build_runner, затем версию SDK и установленные пакеты.
Теперь можно проверить сервер до работы с экраном. В другом терминале учебник предлагает POST на /bargainChefFlow с JSON вида {"data":{"craving":"something warm with chicken"}} и заголовком Accept: text/event-stream. Обёртка data обязательна для обработчика Genkit. В ответ приходят события с частичным результатом и итоговая запись. Это хорошая проверка: если сервер не отвечает, чинить Flutter ещё рано.
Как подключить экран и найти ошибку
Когда сервер работает, Flutter-учебник предлагает создать клиент командой flutter create my_genkit_flutter, затем внутри проекта выполнить flutter pub add genkit. Адрес http://localhost:8080/bargainChefFlow прописан в примере как локальный flowUrl; при своей конфигурации меняешь его на фактический адрес. Браузерное приложение обращается к отдельному серверу и получает поток полей. На физическом телефоне localhost уже означает само устройство, так что для теста на нём потребуется доступный по сети адрес твоего бэкенда. Это следствие сетевой схемы, а не особенность Genkit.
Чтобы увидеть происходящее внутри, ставишь CLI по официальному руководству и запускаешь genkit start -- dart run в каталоге проекта. Developer UI по умолчанию открывается на localhost:4000. Во вкладке Flows можно отправить собственный вход, а в Traces посмотреть, вызывалась ли модель, какой инструмент был использован и что попало в поток. Это полезнее обычного лога «получен ответ»: у ИИ одна неверная цена может родиться в базе скидок, в вызове инструмента или в генерации текста.

Если браузерный клиент не видит сервер, проверь адрес и CORS в консоли разработчика: это две проблемы, которые отдельно перечислены в учебнике. Для API на внешнем адресе добавь авторизацию и квоту на пользователя до выпуска приложения. Иначе любой, кто добрался до твоего endpoint, сможет расходовать модельный бюджет за твой счёт. Код бэкенда и наблюдение за ним остаются обычной разработкой, библиотека не раздаёт бесплатные вызовы модели и не берёт на себя управление твоими платежами.
Где агентная часть действительно полезна
Самое интересное в версии 1.0 для меня - контроль действий, а не слово «агент» на обложке. В анонсе Flutter показан инструмент бронирования: когда модель хочет списать деньги за гостиницу, функция возвращает состояние interrupt; приложение спрашивает человека и только после возобновления разрешает действие. Проверка встроена в код инструмента. Перефразировать промпт и «убедить» модель выполнить платеж без прохождения этого кода недостаточно. Конечно, самому обработчику подтверждения нужны нормальная авторизация и защита от повторного платежа - их фреймворк за тебя не проектирует.
Для менее опасных действий есть middleware - прослойка вокруг генерации, где можно повторить временно упавший вызов, включить дополнительный инструмент или задать правила одобрения. Шаблоны промптов Dotprompt позволяют хранить инструкцию и схему отдельно от виджета. Телеметрия на базе OpenTelemetry помогает смотреть не только текст ответа, но и задержку с расходом токенов. Все эти детали в 1.0 интересны, если у тебя уже есть Flutter-продукт и ты добавляешь в него функцию с измеримой пользой. Ради одного поля «спросить нейросеть» сложный сервер с агентом не нужен.
Стоит ли переносить существующий проект
Если у тебя Flutter-приложение и ты хочешь выдавать структурированные ответы, видеть трассу ошибок или подключить несколько моделей через один слой, Genkit Dart 1.0 уже стоит попробовать на отдельном тестовом flow. Текущий пакет распространяется по Apache 2.0. За фреймворк как за пакет платить не надо; вызовы конкретного провайдера, сервер и хранение истории оплачиваются или лимитируются по условиям тех сервисов, которые ты выбрал. Прайс за токен сюда намеренно не фиксирую: он зависит от модели и регулярно меняется.
Если уже работаешь на ранней версии Genkit Dart, не обновляй её на боевом клиенте одним pub upgrade вслепую. В журнале изменений 1.0 есть несовместимости: переименованы типы, изменён Shelf-адаптер и работа с middleware. Держи тестовую ветку, проверь миграцию старых flows, авторизацию endpoint и показ частичных ответов в приложении. Особое внимание - долгоживущим агентам: ядро 1.0 стабильно, а Agent API всё ещё Beta. Я бы сначала вывел в прод узкий flow, где легко измерить цену одной законченной операции и заметить неправильный результат, а чат с памятью добавил после этого.
Есть конкретная ловушка для уже выпущенного Flutter-клиента. Независимая проверка совместимости и README пакета версии 1.0.0 совпадают: клиент на Genkit 0.17 и старше не распознаёт новый формат сообщения об ошибке в потоке. Пока старые версии приложения остаются у пользователей, новый сервер должен включать GenkitRouter(sendLegacyErrorFrame: true). После обновления клиентов флаг можно убрать. Иначе обычный ответ продолжит приходить, а обработка ошибки неожиданно сломается - очень неприятный вид регрессии.
Источники
- Анонс Genkit Dart 1.0 в блоге Flutter от 8 октября 2026 года
- Карточка Genkit 1.0.0 на pub.dev: минимальная версия Dart и лицензия
- Официальная инструкция по серверу Genkit на Shelf
- Официальная инструкция по подключению Flutter-клиента
- Ограничения стабильности Agent API в документации Genkit
- Журнал несовместимых изменений Genkit 1.0.0
- Независимая проверка миграции: старые Flutter-клиенты и формат ошибок
- README пакета 1.0.0 с опцией совместимости старых клиентов
