Создание приложения с генеративным интерфейсом (GenUI)

1. Введение

В этой практической работе вы узнаете, как создать приложение для списка задач с помощью Flutter, Firebase AI Logic и нового пакета genui. Вы начнете с текстового чат-приложения, добавите в него GenUI, чтобы агент мог создавать собственный интерфейс, и, наконец, создадите собственный интерактивный компонент интерфейса, которым вы и агент сможете управлять напрямую.

Приложение для создания списков задач, запущенное в Chrome

Что вам предстоит сделать

  • Как создать базовый интерфейс чата с помощью Flutter и Firebase AI Logic
  • Интегрируйте пакет genui, чтобы создавать ИИ-интерфейсы
  • Добавьте индикатор выполнения, который будет показывать, что приложение ожидает ответа от агента.
  • Создайте именованную поверхность и покажите ее в специальном месте в интерфейсе.
  • Создание собственного компонента каталога GenUI, который позволяет управлять представлением задач

Что вам понадобится

Эта практическая работа предназначена для разработчиков, имеющих опыт работы с Flutter.

2. Подготовка

Как настроить проект Flutter

  1. Если вы ещё не сделали этого, установите Flutter SDK локально.
  2. Откройте терминал и выполните команду flutter create, чтобы создать новый проект:
    flutter create intro_to_genui
    cd intro_to_genui
    
  3. Добавьте в проект Flutter необходимые зависимости:
    flutter pub add firebase_core firebase_ai genui json_schema_builder
    
    Раздел dependencies должен выглядеть следующим образом (номера версий могут немного отличаться):
    dependencies:
      flutter:
        sdk: flutter
    
      cupertino_icons: ^1.0.9
      firebase_core: ^4.15.0
      firebase_ai: ^4.0.0
      genui: ^0.10.3
      json_schema_builder: ^0.1.7
    
  4. Выполните команду flutter pub get, чтобы скачать все пакеты.Если вы получите уведомление о том, что доступны более новые версии пакетов, выполните команду flutter pub outdated, чтобы проверить версии, и команду flutter pub upgrade, чтобы обновить зависимости.

Как настроить проект Firebase

  1. Если вы ещё этого не сделали, установите интерфейс командной строки Firebase.
  2. Войдите в Firebase, используя аккаунт Google.
    firebase login
    
  3. Установите FlutterFire CLI:
    dart pub global activate flutterfire_cli
    
  4. Чтобы настроить проект Flutter для использования Firebase, выполните в каталоге проекта следующую команду:
    flutterfire configure
    
    Эта команда выполнит следующие действия:
    1. Предложить использовать существующий проект Firebase или создать новый. Выберите Создать новый проект Firebase.
    2. Укажите целевую платформу для приложения Flutter (iOS, Android или веб). Выберите Веб.

Команда flutterfire configure автоматически создает проект Firebase и новое веб-приложение Firebase в этом проекте. Затем команда создает файл конфигурации Firebase (firebase_options.dart) и автоматически добавляет его в каталог lib/ вашего проекта Flutter.

Обратите внимание, что приложение для этой практической работы работает только с Flutter SDK и Chrome, установленными на вашем компьютере (то есть оно создается как веб-приложение). Поскольку это приложение создано с помощью Flutter, оно будет работать и на других платформах. Поэтому в конце практической работы попробуйте повторно запустить flutterfire configure, чтобы добавить поддержку iOS, Android или другой платформы, а затем пересоберите приложение на этой платформе.

Подробную информацию вы найдете в инструкциях по добавлению Firebase в приложение Flutter.

Как настроить Firebase AI Logic

  1. Войдите в консоль Firebase. Используйте тот же аккаунт Google, который вы использовали для входа в интерфейс командной строки Firebase.
  2. Выберите проект Firebase, который вы только что создали с помощью интерфейса командной строки FlutterFire.
  3. В меню навигации слева выберите AI Services (Сервисы ИИ) > AI Logic (Логика ИИ).
  4. Нажмите Начать, чтобы запустить пошаговый процесс.
  5. Выберите Gemini Developer API и следуйте подсказкам на экране, чтобы настроить Firebase AI Logic.

У вас уже есть плагины FlutterFire, необходимые для использования Firebase AI Logic из раздела "Настройка проекта Flutter". На следующем шаге вы сможете приступить к написанию кода приложения.

3. Создание базового интерфейса чата

Прежде чем добавлять генеративный интерфейс, вам нужно создать базовое текстовое чат-приложение на основе Firebase AI Logic. Чтобы быстро начать работу, скопируйте и вставьте весь код для интерфейса чата.

Текстовая версия приложения

Как создать виджет чата

Чтобы показывать текстовые сообщения от пользователя и агента, вашему приложению нужен виджет. Создайте файл с названием lib/message_bubble.dart и добавьте следующий класс:

import 'package:flutter/material.dart';

class MessageBubble extends StatelessWidget {
  final String text;
  final bool isUser;

  const MessageBubble({super.key, required this.text, required this.isUser});

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    final colorScheme = theme.colorScheme;

    final bubbleColor = isUser
        ? colorScheme.primary
        : colorScheme.surfaceContainerHighest;

    final textColor = isUser
        ? colorScheme.onPrimary
        : colorScheme.onSurfaceVariant;

    return Padding(
      padding: const EdgeInsets.symmetric(vertical: 6.0, horizontal: 8.0),
      child: Column(
        crossAxisAlignment: isUser
            ? CrossAxisAlignment.end
            : CrossAxisAlignment.start,
        children: [
          Row(
            mainAxisAlignment: isUser
                ? MainAxisAlignment.end
                : MainAxisAlignment.start,
            children: [
              Flexible(
                child: Container(
                  padding: const EdgeInsets.symmetric(
                    horizontal: 16.0,
                    vertical: 12.0,
                  ),
                  decoration: BoxDecoration(
                    color: bubbleColor,
                    borderRadius: BorderRadius.only(
                      topLeft: const Radius.circular(20),
                      topRight: const Radius.circular(20),
                      bottomLeft: Radius.circular(isUser ? 20 : 0),
                      bottomRight: Radius.circular(isUser ? 0 : 20),
                    ),
                    boxShadow: [
                      BoxShadow(
                        color: Colors.black.withAlpha(20),
                        blurRadius: 4,
                        offset: const Offset(0, 2),
                      ),
                    ],
                    gradient: isUser
                        ? LinearGradient(
                            colors: [
                              colorScheme.primary,
                              colorScheme.primary.withAlpha(200),
                            ],
                            begin: Alignment.topLeft,
                            end: Alignment.bottomRight,
                          )
                        : null,
                  ),
                  child: Text(
                    text,
                    style: theme.textTheme.bodyLarge?.copyWith(
                      color: textColor,
                      height: 1.3,
                    ),
                  ),
                ),
              ),
            ],
          ),
          const SizedBox(height: 2),
        ],
      ),
    );
  }
}

MessageBubble – это StatelessWidget, в котором показывается одно сообщение чата. Он будет использоваться позже в этой практической работе для показа сообщений от вас и агента, но по сути это просто виджет Text.

Как реализовать интерфейс Chat в main.dart

Замените все содержимое файла lib/main.dart следующим кодом реализации чат-бота:

import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'package:intro_to_genui/message_bubble.dart';
import 'firebase_options.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Just Today',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

sealed class ConversationItem {}

class TextItem extends ConversationItem {
  final String text;
  final bool isUser;
  TextItem({required this.text, this.isUser = false});
}

class _MyHomePageState extends State<MyHomePage> {
  final List<ConversationItem> _items = [];
  final _textController = TextEditingController();
  final _scrollController = ScrollController();
  late final ChatSession _chatSession;

  @override
  void initState() {
    super.initState();
    final model = FirebaseAI.googleAI().generativeModel(
      model: 'gemini-3.5-flash',
    );
    _chatSession = model.startChat();
    _chatSession.sendMessage(Content.text(systemInstruction));
  }

  void _scrollToBottom() {
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (_scrollController.hasClients) {
        _scrollController.animateTo(
          _scrollController.position.maxScrollExtent,
          duration: const Duration(milliseconds: 300),
          curve: Curves.easeOut,
        );
      }
    });
  }

  @override
  void dispose() {
    _textController.dispose();
    _scrollController.dispose();
    super.dispose();
  }

  Future<void> _addMessage() async {
    final text = _textController.text;

    if (text.trim().isEmpty) {
      return;
    }
    _textController.clear();

    setState(() {
      _items.add(TextItem(text: text, isUser: true));
    });

    _scrollToBottom();

    final response = await _chatSession.sendMessage(Content.text(text));

    if (response.text?.isNotEmpty ?? false) {
      setState(() {
        _items.add(TextItem(text: response.text!, isUser: false));
      });
      _scrollToBottom();
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: const Text('Just Today'),
      ),
      body: Column(
        children: [
          Expanded(
            child: ListView(
              controller: _scrollController,
              padding: const EdgeInsets.all(16),
              children: [
                for (final item in _items)
                  switch (item) {
                    TextItem() => MessageBubble(
                          text: item.text,
                          isUser: item.isUser,
                        ),
                  },
              ],
            ),
          ),
          SafeArea(
            child: Padding(
              padding: const EdgeInsets.symmetric(horizontal: 16.0),
              child: Row(
                children: [
                  Expanded(
                    child: TextField(
                      controller: _textController,
                      onSubmitted: (_) => _addMessage(),
                      decoration: const InputDecoration(
                        hintText: 'Enter a message',
                      ),
                    ),
                  ),
                  const SizedBox(width: 8),
                  ElevatedButton(
                    onPressed: _addMessage,
                    child: const Text('Send'),
                  ),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}

const systemInstruction = '''
  ## PERSONA
  You are an expert task planner.

  ## GOAL
  Work with me to produce a list of tasks that I should do today, and then track
  the completion status of each one.

  ## RULES
  Talk with me only about tasks that I should do today.
  Do not engage in conversation about any other topic.
  Do not offer suggestions unless I ask for them.
  Do not offer encouragement unless I ask for it.
  Do not offer advice unless I ask for it.
  Do not offer opinions unless I ask for them.

  ## PROCESS
  ### Planning
  *   Ask me for information about tasks that I should do today.
  *   Synthesize a list of tasks from that information.
  *   Ask clarifying questions if you need to.
  *   When you have a list of tasks that you think I should do today, present it
    to me for review.
  *   Respond to my suggestions for changes, if I have any, until I accept the
    list.

  ### Tracking
  *   Once the list is accepted, ask me to let you know when individual tasks are
    complete.
  *   If I tell you a task is complete, mark it as complete.
  *   Once all tasks are complete, send a message acknowledging that, and then
    end the conversation.
''';

Файл main.dart, который вы только что скопировали и вставили, настраивает базовый ChatSession с помощью Firebase AI Logic и запроса в systemInstruction. Он управляет ходом разговора, поддерживая список элементов TextItem и показывая их вместе с запросами пользователей с помощью виджета MessageBubble, который вы создали ранее.

Вот несколько советов, которые помогут вам подготовиться к переходу:

  • Метод initState используется для настройки подключения к Firebase AI Logic.
  • В приложении есть TextField и кнопка для отправки сообщений агенту.
  • Метод _addMessage используется для отправки сообщения пользователя агенту.
  • История чатов хранится в списке _items.
  • Сообщения показываются в ListView с помощью виджета MessageBubble.

Как протестировать приложение

Теперь вы можете запустить приложение и протестировать его.

flutter run -d chrome

Попробуйте поговорить с агентом о задачах, которые вы хотите выполнить сегодня. Текстовый интерфейс справляется с задачей, но GenUI делает процесс проще и быстрее.

После завершения тестирования остановите запущенное приложение, нажав q (или Ctrl+C) в терминале, прежде чем переходить к следующему шагу.

4. Как интегрировать пакет GenUI

Теперь можно перейти с обычного текста на генеративный интерфейс. Вы замените базовый цикл обмена сообщениями Firebase на объекты GenUI Conversation, Catalog и SurfaceController. Это позволяет ИИ-модели создавать реальные виджеты Flutter в чате.

Версия приложения с интегрированным GenUI.

Пакет genui содержит пять классов, которые вы будете использовать в этой практической работе:

  • SurfaceController карт, интерфейс которых сгенерирован моделью на экране.
  • A2uiTransportAdapter связывает внутренние запросы GenUI с любой внешней языковой моделью.
  • Conversation объединяет контроллер и транспортный адаптер в единый API для вашего приложения Flutter.
  • Catalog описывает виджеты и свойства, доступные языковой модели.
  • Surface – это виджет, который показывает интерфейс, сгенерированный моделью.

Подготовка к показу сгенерированного Surface

В lib/main.dart существующий код включает класс TextItem, который представляет одно текстовое сообщение в переписке. Сразу после класса TextItem добавьте класс SurfaceItem, который будет представлять Surface, созданный агентом:

class TextItem extends ConversationItem {
  // ... existing code ...
}

// New!
class SurfaceItem extends ConversationItem {
  final String surfaceId;
  SurfaceItem({required this.surfaceId});
}

Инициализация модулей GenUI

В верхней части файла lib/main.dart импортируйте библиотеку genui:

import 'package:genui/genui.dart' hide TextPart;
import 'package:genui/genui.dart' as genui;

Пакеты genui и firebase_ai включают класс TextPart. Импортируя genui таким образом, вы создаете пространство имен для его версии TextPart как genui.TextPart, избегая конфликта имен.

Объявите основные функциональные контроллеры в _MyHomePageState после _chatSession:

class _MyHomePageState extends State<MyHomePage> {
  // ... existing members
  late final ChatSession _chatSession;

  // Add GenUI controllers
  late final SurfaceController _controller;
  late final A2uiTransportAdapter _transport;
  late final Conversation _conversation;
  late final Catalog catalog;

Затем обновите initState, чтобы подготовить контроллеры библиотеки GenUI.

Удалите эту строку из файла initState:

_chatSession.sendMessage(Content.text(systemInstruction));

Затем добавьте следующий код:

@override
void initState() {
  // ... existing code ...

  // Initialize the GenUI Catalog.
  // The genui package provides a default set of primitive widgets (like text
  // and basic buttons) out of the box using this class.
  catalog = BasicCatalogItems.asCatalog();

  // Create a SurfaceController to manage the state of generated surfaces.
  _controller = SurfaceController(catalogs: [catalog]);

  // Create a transport adapter that will process messages to and from the
  // agent, looking for A2UI messages.
  _transport = A2uiTransportAdapter(onSend: _sendAndReceive);

  // Link the transport and SurfaceController together in a Conversation,
  // which provides your app a unified API for interacting with the agent.
  _conversation = Conversation(
    controller: _controller,
    transport: _transport,
  );
}

Этот код создает фасад Conversation, который управляет контроллером и адаптером. В этом диалоге приложению предоставляется поток событий, которые оно может использовать, чтобы следить за тем, что создает агент, а также метод отправки сообщений агенту.

Затем создайте прослушиватель для событий разговора. К ним относятся события, связанные с интерфейсом, а также события для текстовых сообщений и ошибок:

@override
void initState() {
  // ... existing code ...

  // Listen to GenUI stream events to update the UI
  _conversation.events.listen((event) {
    setState(() {
      switch (event) {
        case ConversationSurfaceAdded added:
          _items.add(SurfaceItem(surfaceId: added.surfaceId));
          _scrollToBottom();
        case ConversationSurfaceRemoved removed:
          _items.removeWhere(
            (item) =>
                item is SurfaceItem && item.surfaceId == removed.surfaceId,
          );
        case ConversationContentReceived content:
          _items.add(TextItem(text: content.text, isUser: false));
          _scrollToBottom();
        case ConversationError error:
          debugPrint('GenUI Error: ${error.error}');
        default:
      }
    });
  });
}

Наконец, создайте системный запрос и отправьте его агенту:

  @override
  void initState() {
    // ... existing code ...

    // Create the system prompt for the agent, which will include this app's
    // system instruction as well as the schema for the catalog.
    final promptBuilder = PromptBuilder.chat(
      catalog: catalog,
      systemPromptFragments: [systemInstruction],
    );

    // Send the prompt into the Conversation, which will subsequently route it
    // to Firebase using the transport mechanism.
    _conversation.sendRequest(
      ChatMessage.system(promptBuilder.systemPromptJoined()),
    );
  }

Также обновите метод dispose() в _MyHomePageState, чтобы новые контроллеры GenUI правильно очищались при удалении виджета:

  @override
  void dispose() {
    _conversation.dispose();
    _transport.dispose();
    _controller.dispose();
    _textController.dispose();
    _scrollController.dispose();
    super.dispose();
  }

Медийные платформы

Затем обновите метод ListView объекта build, чтобы показывать объекты SurfaceItem в списке _items:

Expanded(
  child: ListView(
    controller: _scrollController,
    padding: const EdgeInsets.all(16),
    children: [
      for (final item in _items)
        switch (item) {
          TextItem() => MessageBubble(
            text: item.text,
            isUser: item.isUser,
          ),
          // New!
          SurfaceItem() => Surface(
            surfaceContext: _controller.contextFor(
              item.surfaceId,
            ),
          ),
        },
    ],
  ),
),

Конструктор виджета Surface принимает surfaceContext, который указывает, какую поверхность он должен отображать. Созданный ранее SurfaceController, _controller, предоставляет определение и состояние для каждой поверхности и обеспечивает ее перестроение при обновлении.

Как подключить GenUI к Firebase AI Logic

В пакете genui используется подход "Принеси свою модель", то есть вы сами выбираете, какая LLM будет использоваться. В этом случае вы используете Firebase AI Logic, но пакет предназначен для работы с различными агентами и поставщиками.

Такая свобода накладывает дополнительную ответственность: вам нужно брать сообщения, сгенерированные пакетом genui, и отправлять их выбранному агенту, а также брать ответы агента и отправлять их обратно в genui.

Для этого вы определите метод _sendAndReceive, на который ссылается код из предыдущего шага. В lib/main.dart добавьте _sendAndReceive в класс _MyHomePageState (например, сразу после строки late final Catalog catalog;):

class _MyHomePageState extends State<MyHomePage> {
  // ... existing code ...
  late final Catalog catalog;

  // New!
  Future<void> _sendAndReceive(ChatMessage msg) async {
    final buffer = StringBuffer();

    // Reconstruct the message part fragments
    for (final part in msg.parts) {
      if (part.isUiInteractionPart) {
        buffer.write(part.asUiInteractionPart!.interaction);
      } else if (part is genui.TextPart) {
        buffer.write(part.text);
      }
    }

    if (buffer.isEmpty) {
      return;
    }

    final text = buffer.toString();

    // Send the string to Firebase AI Logic.
    final response = await _chatSession.sendMessage(Content.text(text));

    if (response.text?.isNotEmpty ?? false) {
      // Feed the response back into GenUI's transportation layer
      _transport.addChunk(response.text!);
    }
  }

Пакет genui будет вызывать этот метод каждый раз, когда ему нужно отправить сообщение агенту. Вызов addChunk в конце метода возвращает ответ агента в пакет genui, позволяя ему обработать ответ и сгенерировать интерфейс.

Наконец, полностью замените существующий метод _addMessage этой новой версией, чтобы он направлял сообщения в Conversation, а не напрямую в Firebase:

  Future<void> _addMessage() async {
    final text = _textController.text;

    if (text.trim().isEmpty) {
      return;
    }

    _textController.clear();

    setState(() {
      _items.add(TextItem(text: text, isUser: true));
    });

    _scrollToBottom();

    // Send the user's input through GenUI instead of directly to Firebase.
    await _conversation.sendRequest(ChatMessage.user(text));
  }

Готово! Попробуйте запустить приложение снова. Помимо текстовых сообщений, вы увидите, как агент генерирует элементы интерфейса, такие как кнопки, текстовые виджеты и т. д.

Вы даже можете попросить агента показать интерфейс определенным образом. Например, попробуйте такой запрос: "Покажи мои задачи в столбце с кнопкой для отметки каждой из них как выполненной".

5. Добавить состояние ожидания

Генерация LLM выполняется асинхронно. Пока пользователь ждет ответа, в интерфейсе чата должны быть отключены кнопки ввода и должен отображаться индикатор выполнения, чтобы пользователь знал, что GenUI создает контент. К счастью, пакет genui предоставляет Listenable, который можно использовать для отслеживания состояния разговора. Значение ConversationState включает свойство isWaiting, которое определяет, генерирует ли модель контент.

Оберните элементы управления вводом в тег ValueListenableBuilder

В методе build класса _MyHomePageState в файле lib/main.dart найдите виджет SafeArea в нижней части Column и оберните его дочерний элемент Row (который содержит TextField и ElevatedButton) в элемент ValueListenableBuilder, который прослушивает _conversation.state. Проверяя state.isWaiting, вы можете отключить ввод, пока модель генерирует контент:

SafeArea(
  child: Padding(
    padding: const EdgeInsets.symmetric(horizontal: 16.0),
    // Wrap the Row in a ValueListenableBuilder:
    child: ValueListenableBuilder<ConversationState>(
      valueListenable: _conversation.state,
      builder: (context, state, child) {
        return Row(
          children: [
            Expanded(
              child: TextField(
                controller: _textController,
                // Also disable the Enter key submission when waiting!
                onSubmitted: state.isWaiting ? null : (_) => _addMessage(),
                decoration: const InputDecoration(
                  hintText: 'Enter a message',
                ),
              ),
            ),
            const SizedBox(width: 8),
            ElevatedButton(
              // Disable the send button when the model is generating
              onPressed: state.isWaiting ? null : _addMessage,
              child: const Text('Send'),
            ),
          ],
        );
      },
    ),
  ),
),

Добавьте индикатор выполнения

В методе build класса _MyHomePageState оберните основной виджет Column в Stack и добавьте ValueListenableBuilder, который отображает LinearProgressIndicator в качестве второго дочернего элемента этого Stack. После этого body вашего Scaffold должен выглядеть так:

body: Stack( // New!
  children: [
    Column(
      children: [
        // ... existing Expanded and SafeArea widgets ...
      ],
    ),
    // Listen to the state again, this time to render a progress indicator
    ValueListenableBuilder<ConversationState>(
      valueListenable: _conversation.state,
      builder: (context, state, child) {
        if (state.isWaiting) {
          return const LinearProgressIndicator();
        }
        return const SizedBox.shrink();
      },
    ),
  ],
),

6. Сохранение интерфейса GenUI

До сих пор список задач отображался в прокручиваемом чате, и каждое новое сообщение или поверхность добавлялись в список по мере поступления. На следующем шаге вы узнаете, как назвать поверхность и отобразить ее в определенном месте интерфейса.

Сначала в верхней части файла lib/main.dart перед void main() объявите константу, которая будет использоваться в качестве идентификатора поверхности:

const taskDisplaySurfaceId = 'task_display';

Затем в файле initState() обновите оператор switch в прослушивателе Conversation, чтобы убедиться, что ни одна поверхность с этим идентификатором не добавлена в _items. Для этого обновите ветвь case ConversationSurfaceAdded added: внутри _conversation.events.listen, заключив строки _items.add(...) и _scrollToBottom() в оператор if:

_conversation.events.listen((event) {
  setState(() {
    switch (event) {
      case ConversationSurfaceAdded added:
        // Wrap these two lines in an if check:
        if (added.surfaceId != taskDisplaySurfaceId) {
          _items.add(SurfaceItem(surfaceId: added.surfaceId));
          _scrollToBottom();
        }
      case ConversationSurfaceRemoved removed:
        // ... existing code ...

Затем откройте структуру макета дерева виджетов в _MyHomePageState.build, чтобы создать место для закрепленного элемента непосредственно перед журналом чата. Вставьте AnimatedSize и const Divider() в качестве первых двух дочерних элементов основного элемента Column, прямо перед кодом Expanded(child: ListView(...)):

body: Stack(
  children: [
    Column(
      children: [
        // Insert these two new widgets at the top of the Column:
        AnimatedSize(
          duration: const Duration(milliseconds: 300),
          child: Container(
            padding: const EdgeInsets.all(16),
            alignment: Alignment.topLeft,
            child: Surface(
              surfaceContext: _controller.contextFor(
                taskDisplaySurfaceId,
              ),
            ),
          ),
        ),
        const Divider(),
        Expanded(
          child: ListView(
            // ... existing code ...

До сих пор ваш агент мог создавать и использовать поверхности по своему усмотрению. Чтобы дать ему более конкретные инструкции, вам нужно вернуться к системному запросу. Добавьте следующий раздел ## USER INTERFACE в конец запроса, хранящегося в константе systemInstruction:

const systemInstruction = '''
  // ... existing prompt content ...

  ## USER INTERFACE
  *   To display the list of tasks create one and only one instance of the
    TaskDisplay catalog item. Use "$taskDisplaySurfaceId" as its surface ID.
  *   Update $taskDisplaySurfaceId as necessary when the list changes.
  *   $taskDisplaySurfaceId must include a button for each task that I can use
    to mark it complete. When I use that button to mark a task complete, it
    should send you a message indicating what I've done.
  *   Avoid repeating the same information in a single message.
  *   When responding with text, rather than A2UI messages, be brief.
''';

Важно дать агенту четкие инструкции о том, когда и как использовать элементы интерфейса. Указав агенту, какой объект каталога и идентификатор платформы использовать (и что нужно повторно использовать один экземпляр), вы можете быть уверены, что он создаст нужный вам интерфейс.

Предстоит ещё много работы, но вы можете попробовать запустить приложение снова, чтобы увидеть, как агент создает область отображения задач в верхней части интерфейса.

7. Как создать виджет каталога

На данный момент объект каталога TaskDisplay не существует. На следующих шагах вы создадите схему данных, класс для ее анализа, виджет и элемент каталога, который объединит все это.

Сначала создайте файл task_display.dart в каталоге lib/ проекта и добавьте следующие импорты:

import 'package:flutter/material.dart';
import 'package:genui/genui.dart';
import 'package:json_schema_builder/json_schema_builder.dart';

Как создать схему данных

Затем определите схему данных, которую агент будет предоставлять, когда захочет создать отображение задачи. В этом процессе используются некоторые конструкторы из пакета json_schema_builder, но по сути вы просто определяете схему JSON, используемую в сообщениях, отправляемых агенту и получаемых от него.

Начните с базового селектора S.object, ссылающегося на название компонента:

final taskDisplaySchema = S.object(
  properties: {
    'component': S.string(enumValues: ['TaskDisplay']),
  },
);

Затем добавьте в свойства схемы title, tasks, name, isCompleted и completeAction.

final taskDisplaySchema = S.object(
  properties: {
    'component': S.string(enumValues: ['TaskDisplay']),
    'title': S.string(description: 'The title of the task list'),
    'tasks': S.list(
      description: 'A list of tasks to be completed today',
      items: S.object(
        properties: {
          'name': S.string(description: 'The name of the task to be completed'),
          'isCompleted': S.boolean(
            description: 'Whether the task is completed',
          ),
          'completeAction': A2uiSchemas.action(
            description:
                'The action performed when the user has completed the task.',
          ),
        },
      ),
    ),
  },
);

Посмотрите на свойство completeAction. Он создается с помощью A2uiSchemas.action – конструктора для свойства схемы, которое представляет действие A2UI. Добавляя действие в схему, приложение сообщает агенту: "Когда ты даешь мне задание, также предоставь название и метаданные действия, которое я могу использовать, чтобы сообщить тебе о выполнении задания". Позже приложение вызовет это действие, когда пользователь нажмет на флажок.

Затем добавьте в схему поля required. Они указывают агенту, какие свойства нужно заполнять каждый раз. В этом случае обязательны все свойства.

final taskDisplaySchema = S.object(
  properties: {
    'component': S.string(enumValues: ['TaskDisplay']),
    'title': S.string(description: 'The title of the task list'),
    'tasks': S.list(
      description: 'A list of tasks to be completed today',
      items: S.object(
        properties: {
          'name': S.string(description: 'The name of the task to be completed'),
          'isCompleted': S.boolean(
            description: 'Whether the task is completed',
          ),
          'completeAction': A2uiSchemas.action(
            description:
                'The action performed when the user has completed the task.',
          ),
        },
        // New!
        required: ['name', 'isCompleted', 'completeAction'],
      ),
    ),
  },
  // New!
  required: ['title', 'tasks'],
);

Как создать классы для синтаксического анализа данных

При создании экземпляров этого компонента агент будет отправлять данные, соответствующие схеме. Добавьте два класса для преобразования входящего JSON в объекты Dart со строгой типизацией. Обратите внимание, как _TaskDisplayData обрабатывает корневую структуру, делегируя синтаксический анализ внутреннего массива _TaskData.

class _TaskData {
  final String name;
  final bool isCompleted;
  final String actionName;
  final JsonMap? actionContext;

  _TaskData({
    required this.name,
    required this.isCompleted,
    required this.actionName,
    this.actionContext,
  });

  factory _TaskData.fromJson(Map<String, Object?> json) {
    try {
      final action = json['completeAction']! as JsonMap;
      final event = action['event']! as JsonMap;

      return _TaskData(
        name: json['name'] as String,
        isCompleted: json['isCompleted'] as bool,
        actionName: event['name'] as String,
        actionContext: event['context'] as JsonMap?,
      );
    } catch (e) {
      throw Exception('Invalid JSON for _TaskData: $e');
    }
  }
}

class _TaskDisplayData {
  final String title;
  final List<_TaskData> tasks;

  _TaskDisplayData({required this.title, required this.tasks});

  factory _TaskDisplayData.fromJson(Map<String, Object?> json) {
    try {
      return _TaskDisplayData(
        title: (json['title'] as String?) ?? 'Tasks',
        tasks: (json['tasks'] as List<Object?>)
            .map((e) => _TaskData.fromJson(e as Map<String, Object?>))
            .toList(),
      );
    } catch (e) {
      throw Exception('Invalid JSON for _TaskDisplayData: $e');
    }
  }
}

Если вы уже работали с Flutter, то, скорее всего, создавали похожие классы. Они принимают JsonMap и возвращают строго типизированный объект, содержащий данные, полученные из JSON.

Проверьте поля actionName и actionContext в файле _TaskData. Они извлекаются из свойства completeAction JSON и содержат название действия и его контекст данных (ссылку на местоположение действия в модели данных GenUI). Они будут использоваться позже для создания UserActionEvent.

Модель данных – это централизованное хранилище, в котором можно отслеживать все динамические состояния интерфейса. Она поддерживается библиотекой genui. Когда агент создает компонент интерфейса на основе каталога, он также создает объект данных, соответствующий схеме компонента. Этот объект данных хранится в модели данных на стороне клиента, поэтому его можно использовать для создания виджетов и ссылаться на него в последующих сообщениях агенту (например, в completeAction, который вы собираетесь подключить к виджету).

Как добавить виджет

Теперь создайте виджет для отображения списка. Он должен принимать экземпляр класса _TaskDisplayData и обратный вызов, который будет вызываться по завершении задачи.

class _TaskDisplay extends StatelessWidget {
  final _TaskDisplayData data;
  final void Function(_TaskData) onCompleteTask;

  const _TaskDisplay({required this.data, required this.onCompleteTask});

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      children: [
        Padding(
          padding: const EdgeInsets.all(16.0),
          child: Text(
            data.title,
            style: Theme.of(context).textTheme.titleLarge,
          ),
        ),
        ...data.tasks.map(
          (task) => CheckboxListTile(
            title: Text(
              task.name,
              style: TextStyle(
                decoration: task.isCompleted
                    ? TextDecoration.lineThrough
                    : TextDecoration.none,
              ),
            ),
            value: task.isCompleted,
            onChanged: task.isCompleted
                ? null
                : (val) {
                    if (val == true) {
                      onCompleteTask(task);
                    }
                  },
          ),
        ),
      ],
    );
  }
}

Создайте CatalogItem

После того как вы создали схему, парсер и виджет, можно создать CatalogItem, чтобы связать их вместе.

В нижней части файла task_display.dart создайте переменную верхнего уровня taskDisplay, используйте _TaskDisplayData для анализа входящего JSON и создайте экземпляр виджета _TaskDisplay.

final taskDisplay = CatalogItem(
  name: 'TaskDisplay',
  dataSchema: taskDisplaySchema,
  widgetBuilder: (itemContext) {
    final json = itemContext.data as Map<String, Object?>;
    final data = _TaskDisplayData.fromJson(json);

    return _TaskDisplay(
      data: data,
      onCompleteTask: (task) async {
        // We will implement this next!
      },
    );
  },
);

Реализуйте onCompleteTask

Чтобы виджет работал, он должен отправлять агенту информацию о выполнении задачи. Замените пустой плейсхолдер onCompleteTask следующим кодом, чтобы создать и отправить событие с помощью completeAction из данных задачи.

onCompleteTask: (task) async {
  // A data context is a reference to a location in the data model. This line
  // turns that reference into a concrete data object that the agent can use.
  // It's kind of like taking a pointer and replacing it with the value it
  // points to.
  final JsonMap resolvedContext = await resolveContext(
    itemContext.dataContext,
    task.actionContext,
  );

  // Dispatch an event back to the agent, letting it know a task was completed.
  // This will be sent to the agent in an A2UI message that includes the name
  // of the action, the surface ID, and the resolved data context.
  itemContext.dispatchEvent(
    UserActionEvent(
      name: task.actionName,
      sourceComponentId: itemContext.id,
      context: resolvedContext,
    ),
  );
}

Зарегистрировать объект каталога

Наконец, откройте main.dart, импортируйте новый файл и зарегистрируйте его вместе с другими объектами каталога.

Добавьте этот импорт в начало lib/main.dart:

import 'task_display.dart';

Замените catalog = BasicCatalogItems.asCatalog(); в функции initState() на:

// The Catalog is immutable, so use copyWith to create a new version
// that includes our custom catalog item along with the basics.
catalog = BasicCatalogItems.asCatalog().copyWith(newItems: [taskDisplay]);

Готово! Чтобы увидеть изменения, перезапустите приложение.

8. Попробуйте разные способы взаимодействия с агентом

Приложение со списком задач, запущенное в Chrome.

Теперь, когда вы добавили новый виджет в каталог и освободили для него место в интерфейсе приложения, пришло время поработать с агентом. Одно из главных преимуществ GenUI заключается в том, что он предлагает два способа взаимодействия с данными: через интерфейс приложения, например с помощью кнопок и флажков, и через агента, который понимает естественный язык и может рассуждать о данных. Попробуйте оба варианта.

  • Опишите в текстовом поле три или четыре задачи, и они появятся в списке.
  • Чтобы отметить задачу как выполненную или невыполненную, используйте флажок.
  • Составьте список из 5–6 задач, а затем попросите агента удалить те, которые требуют поездки.
  • Попросите агента создать список повторяющихся задач в виде отдельных пунктов ("Мне нужно купить праздничные открытки для мамы, папы и бабушки. Создай для них отдельные задачи").
  • Попросите агента отметить все задачи как выполненные или невыполненные или установить флажки рядом с первыми двумя или тремя задачами.

9. Поздравляю!

Поздравляем! Вы создали приложение для отслеживания задач на основе искусственного интеллекта, используя генеративный интерфейс и Flutter.

Что вы узнали

  • Как взаимодействовать с базовыми моделями Google с помощью Flutter Firebase SDK
  • Отображение интерактивных элементов, созданных Gemini с помощью GenUI
  • Закрепление поверхностей в макетах с помощью заранее определенных статических идентификаторов отрисовки
  • Разработка пользовательских схем и каталогов виджетов для надежных циклов взаимодействия

Справочная документация