Créer une application d'interface utilisateur générative (GenUI)

1. Introduction

Dans cet atelier de programmation, vous allez créer une application de liste de tâches à l'aide de Flutter, de Firebase AI Logic et du nouveau package genui. Vous commencerez par une application de chat textuel, que vous améliorerez avec GenUI pour permettre à l'agent de créer sa propre UI. Enfin, vous créerez votre propre composant d'UI interactif et personnalisé, que vous et l'agent pourrez manipuler directement.

Une application de liste de tâches exécutée dans Chrome

Objectifs de l'atelier

  • Créer une interface de chat de base à l'aide de Flutter et de Firebase AI Logic
  • Intégrez le package genui pour générer des surfaces basées sur l'IA.
  • Ajouter une barre de progression pour indiquer quand l'application attend une réponse de l'agent
  • Créez une surface nommée et affichez-la dans un emplacement dédié de l'UI.
  • Créez un composant de catalogue GenUI personnalisé qui vous permet de contrôler la façon dont les tâches sont présentées.

Prérequis

Cet atelier de programmation s'adresse aux développeurs Flutter de niveau intermédiaire.

2. Avant de commencer

Configurer le projet Flutter

  1. Si vous ne l'avez pas déjà fait, installez le SDK Flutter localement.
  2. Ouvrez votre terminal et exécutez flutter create pour créer un projet :
    flutter create intro_to_genui
    cd intro_to_genui
    
  3. Ajoutez les dépendances nécessaires à votre projet Flutter :
    flutter pub add firebase_core firebase_ai genui json_schema_builder
    
    La section dependencies finale doit se présenter comme suit (les numéros de version peuvent varier légèrement) :
    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. Exécutez flutter pub get pour télécharger tous les packages.Si un message vous indique que des versions plus récentes des packages sont disponibles, vous pouvez exécuter flutter pub outdated pour vérifier les versions et flutter pub upgrade pour mettre à jour vos dépendances.

Configurer un projet Firebase

  1. Si ce n'est pas déjà fait, installez la CLI Firebase.
  2. Connectez-vous à Firebase avec votre compte Google :
    firebase login
    
  3. Installez la CLI FlutterFire :
    dart pub global activate flutterfire_cli
    
  4. Depuis le répertoire de votre projet Flutter, exécutez la commande suivante pour configurer votre projet Flutter afin qu'il utilise Firebase :
    flutterfire configure
    
    Cette commande effectue les opérations suivantes :
    1. vous demande si vous souhaitez utiliser un projet Firebase existant ou en créer un. Sélectionnez Créer un projet Firebase.
    2. Vous demander quelle plate-forme (iOS, Android, Web) vous souhaitez cibler pour votre application Flutter. Pour l'instant, sélectionnez Web.

La commande flutterfire configure crée automatiquement un projet Firebase et une application Web Firebase dans ce projet. La commande crée ensuite un fichier de configuration Firebase (firebase_options.dart) et l'ajoute automatiquement au répertoire lib/ de votre projet Flutter.

Notez que l'application de cet atelier de programmation fonctionne uniquement avec le SDK Flutter et Chrome installés sur votre ordinateur (c'est-à-dire qu'elle est compilée en tant qu'application Web). Toutefois, comme cette application est conçue avec Flutter, elle fonctionnera également sur d'autres plates-formes. À la fin de l'atelier de programmation, essayez de réexécuter flutterfire configure pour ajouter la prise en charge d'iOS, d'Android ou d'une autre plate-forme, puis de recompiler l'application sur cette plate-forme.

Pour en savoir plus, consultez les instructions pour ajouter Firebase à une application Flutter.

Configurer Firebase AI Logic

  1. Connectez-vous à la console Firebase. Utilisez le même compte Google que celui que vous avez utilisé pour vous connecter à la CLI Firebase.
  2. Sélectionnez le projet Firebase que vous venez de créer à l'aide de la CLI FlutterFire.
  3. Dans le menu de navigation de gauche, sélectionnez Services d'IA > Logique d'IA.
  4. Cliquez sur Commencer pour lancer le workflow guidé.
  5. Sélectionnez cette option pour commencer avec l'API Gemini Developer, puis suivez les instructions à l'écran pour configurer Firebase AI Logic.

Vous disposez déjà des plug-ins FlutterFire requis pour utiliser Firebase AI Logic, comme indiqué dans la section "Configurer un projet Flutter". Vous êtes prêt à passer au codage de votre application à l'étape suivante.

3. Créer une interface de chat de base

Avant d'introduire l'UI générative, votre application a besoin d'une base : une application de chat textuel de base optimisée par Firebase AI Logic. Pour ne pas perdre de temps, vous allez copier-coller l'intégralité de la configuration de l'interface de chat.

Une version textuelle de l'application

Créer le widget de bulle de message

Pour afficher les messages de l'utilisateur et de l'agent, votre application a besoin d'un widget. Créez un fichier nommé lib/message_bubble.dart et ajoutez la classe suivante :

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 est un StatelessWidget qui affiche un seul message de chat. Il sera utilisé plus tard dans cet atelier de programmation pour afficher vos messages et ceux de l'agent, mais il s'agit principalement d'un widget Text sophistiqué.

Implémenter l'UI de chat dans main.dart

Remplacez l'intégralité du contenu de lib/main.dart par cette implémentation complète de chatbot textuel :

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.
''';

Le fichier main.dart que vous venez de copier-coller configure un ChatSession de base à l'aide de Firebase AI Logic et du prompt dans systemInstruction. Il gère les tours de conversation en conservant une liste d'éléments TextItem et en les affichant à côté des requêtes utilisateur à l'aide du widget MessageBubble que vous avez créé précédemment.

Voici quelques points à vérifier avant de continuer :

  • La méthode initState permet de configurer la connexion à Firebase AI Logic.
  • L'application propose un TextField et un bouton permettant d'envoyer des messages à l'agent.
  • La méthode _addMessage permet d'envoyer le message de l'utilisateur à l'agent.
  • La liste _items est l'emplacement où l'historique des conversations est stocké.
  • Les messages sont affichés dans un ListView à l'aide du widget MessageBubble.

Tester l'application

Une fois cette étape terminée, vous pouvez exécuter l'application et la tester.

flutter run -d chrome

Essayez de discuter avec l'agent des tâches que vous souhaitez accomplir aujourd'hui. Bien qu'une interface utilisateur purement textuelle puisse faire l'affaire, l'UI générative peut rendre l'expérience plus facile et plus rapide.

Une fois les tests terminés, arrêtez l'application en cours d'exécution en appuyant sur q (ou Ctrl+C) dans le terminal avant de passer à l'étape suivante.

4. Intégrer le package GenUI

Il est maintenant temps de passer du texte brut à l'UI générative. Vous allez remplacer la boucle de messagerie Firebase de base par les objets GenUI Conversation, Catalog et SurfaceController. Cela permet au modèle d'IA d'instancier des widgets Flutter réels dans le flux de discussion.

Une version de l'application avec GenUI intégré

Le package genui fournit cinq classes que vous utiliserez tout au long de cet atelier de programmation :

  • SurfaceController mappe l'UI générée par le modèle à l'écran.
  • A2uiTransportAdapter relie les requêtes GenUI internes à n'importe quel modèle de langage externe.
  • Conversation encapsule le contrôleur et l'adaptateur de transport avec une seule API unifiée pour votre application Flutter.
  • Catalog décrit les widgets et les propriétés disponibles pour le modèle de langage.
  • Surface est un widget qui affiche l'UI générée par le modèle.

Préparez-vous à afficher un Surface généré

Dans lib/main.dart, le code existant inclut une classe TextItem qui représente un seul message dans la conversation. Juste après la classe TextItem, ajoutez une classe SurfaceItem pour représenter un Surface créé par l'agent :

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

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

Initialiser les composants de base de GenUI

En haut de lib/main.dart, importez la bibliothèque genui :

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

Les packages genui et firebase_ai incluent une classe TextPart. En important genui de cette manière, vous attribuez un espace de noms à sa version de TextPart en tant que genui.TextPart, ce qui évite un conflit de noms.

Déclarez les contrôleurs fonctionnels de base dans _MyHomePageState après _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;

Ensuite, mettez à jour initState pour préparer les contrôleurs de la bibliothèque GenUI.

Supprimez cette ligne de initState :

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

Ajoutez ensuite le code suivant :

@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,
  );
}

Ce code crée une façade Conversation qui gère le contrôleur et l'adaptateur. Cette conversation fournit à votre application un flux d'événements qu'elle peut utiliser pour suivre ce que l'agent crée, ainsi qu'une méthode pour envoyer des messages à l'agent.

Ensuite, créez un écouteur pour les événements de conversation. Il s'agit des événements liés à la surface, ainsi que de ceux concernant les messages et les erreurs :

@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:
      }
    });
  });
}

Enfin, créez le prompt système et envoyez-le à l'agent :

  @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()),
    );
  }

Mettez également à jour la méthode dispose() dans _MyHomePageState afin que les contrôleurs GenUI nouvellement ajoutés soient correctement nettoyés lorsque le widget est supprimé :

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

Surfaces d'affichage

Ensuite, mettez à jour la méthode build de ListView pour afficher les SurfaceItem dans la liste _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,
            ),
          ),
        },
    ],
  ),
),

Le constructeur du widget Surface utilise un surfaceContext qui lui indique la surface qu'il doit afficher. Le SurfaceController créé précédemment, _controller, fournit la définition et l'état de chaque surface, et s'assure qu'il se reconstruit en cas de mise à jour.

Connecter GenUI à Firebase AI Logic

Le package genui utilise une approche "Bring Your Own Model" (Apportez votre propre modèle), ce qui signifie que vous contrôlez le LLM qui alimente votre expérience. Dans ce cas, vous utilisez Firebase AI Logic, mais le package est conçu pour fonctionner avec différents agents et fournisseurs.

Cette liberté s'accompagne d'une responsabilité supplémentaire : vous devez prendre les messages générés par le package genui et les envoyer à l'agent de votre choix, puis prendre les réponses de l'agent et les renvoyer dans genui.

Pour ce faire, vous allez définir la méthode _sendAndReceive référencée dans le code de l'étape précédente. Dans lib/main.dart, ajoutez _sendAndReceive dans la classe _MyHomePageState (par exemple, juste après la ligne 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!);
    }
  }

Cette méthode sera appelée par le package genui chaque fois qu'il devra envoyer un message à l'agent. L'appel à addChunk à la fin de la méthode renvoie la réponse de l'agent dans le package genui, ce qui lui permet de traiter la réponse et de générer l'UI.

Enfin, remplacez entièrement votre méthode _addMessage existante par cette nouvelle version, afin qu'elle achemine les messages vers Conversation au lieu de Firebase directement :

  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));
  }

Et voilà ! Essayez d'exécuter à nouveau l'application. En plus des messages, vous verrez l'agent générer des surfaces d'UI telles que des boutons, des widgets de texte et plus encore.

Vous pouvez même essayer de demander à l'agent d'afficher l'UI d'une manière particulière. Par exemple, essayez un message comme "Affiche mes tâches dans une colonne, avec un bouton pour marquer chacune d'elles comme terminée."

5. Ajouter un état d'attente

La génération de LLM est asynchrone. En attendant une réponse, l'interface de chat doit désactiver les boutons de saisie et afficher un indicateur de progression pour que l'utilisateur sache que GenUI est en train de créer du contenu. Heureusement, le package genui fournit un Listenable que vous pouvez utiliser pour suivre l'état de la conversation. Cette valeur ConversationState inclut une propriété isWaiting pour déterminer si le modèle génère du contenu.

Encapsulez les contrôles d'entrée avec un ValueListenableBuilder.

Dans la méthode build de _MyHomePageState dans lib/main.dart, localisez le widget SafeArea en bas de Column et encapsulez son enfant Row (qui contient vos TextField et ElevatedButton) avec un ValueListenableBuilder qui écoute _conversation.state. En inspectant state.isWaiting, vous pouvez désactiver la saisie pendant que le modèle génère du contenu :

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'),
            ),
          ],
        );
      },
    ),
  ),
),

Ajouter une barre de progression

Dans la méthode build de _MyHomePageState, encapsulez le widget Column principal dans un Stack, puis ajoutez un ValueListenableBuilder qui affiche un LinearProgressIndicator en tant que deuxième enfant de ce Stack. Une fois que vous avez terminé, le body de votre Scaffold doit se présenter comme suit :

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. Conserver une surface GenUI

Jusqu'à présent, la liste des tâches s'affichait dans le flux de chat défilant, chaque nouveau message ou surface étant ajouté à la liste au fur et à mesure de son arrivée. À l'étape suivante, vous verrez comment nommer une surface et l'afficher à un emplacement spécifique de l'interface utilisateur.

Tout d'abord, en haut de lib/main.dart, avant void main(), déclarez une constante à utiliser comme ID de surface :

const taskDisplaySurfaceId = 'task_display';

Ensuite, dans initState(), mettez à jour l'instruction switch dans l'écouteur Conversation pour vous assurer qu'aucune surface avec cet ID n'est ajoutée à _items. Pour ce faire, mettez à jour la branche case ConversationSurfaceAdded added: dans _conversation.events.listen en encapsulant les lignes _items.add(...) et _scrollToBottom() dans une instruction 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 ...

Ensuite, ouvrez la structure de mise en page de l'arborescence de widgets dans _MyHomePageState.build pour créer un espace pour la surface épinglée juste avant votre journal de chat. Insérez AnimatedSize et const Divider() en tant que deux premiers enfants de l'élément Column principal, juste avant le code 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 ...

Jusqu'à présent, votre agent était libre de créer et d'utiliser des surfaces comme il l'entendait. Pour lui donner des instructions plus spécifiques, vous devez revenir à l'invite système. Ajoutez la section ## USER INTERFACE suivante à la fin de la requête stockée dans la constante 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.
''';

Il est important de donner à votre agent des instructions claires sur le moment et la manière d'utiliser les surfaces d'interface utilisateur. En indiquant à l'agent d'utiliser un ID de surface et un élément de catalogue spécifiques (et de réutiliser une seule instance), vous pouvez vous assurer qu'il crée l'interface que vous souhaitez voir.

Il reste encore du travail, mais vous pouvez essayer d'exécuter à nouveau votre application pour voir l'agent créer la surface d'affichage des tâches en haut de l'interface utilisateur.

7. Créer votre widget de catalogue personnalisé

À ce stade, l'élément de catalogue TaskDisplay n'existe pas. Dans les étapes suivantes, vous allez résoudre ce problème en créant un schéma de données, une classe pour analyser ce schéma, un widget et l'élément de catalogue qui rassemble le tout.

Tout d'abord, créez un fichier nommé task_display.dart dans le répertoire lib/ de votre projet et ajoutez les importations suivantes :

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

Créer le schéma de données

Ensuite, définissez le schéma de données que l'agent fournira lorsqu'il voudra créer un affichage de tâche. Le processus utilise des constructeurs sophistiqués du package json_schema_builder, mais vous définissez essentiellement un schéma JSON utilisé dans les messages envoyés à l'agent et reçus de sa part.

Commencez par un S.object de base faisant référence au nom du composant :

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

Ensuite, ajoutez title, tasks, name, isCompleted et completeAction aux propriétés du schéma.

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.',
          ),
        },
      ),
    ),
  },
);

Examinez la propriété completeAction. Il est créé avec A2uiSchemas.action, le constructeur d'une propriété de schéma qui représente une action A2UI. En ajoutant une action au schéma, l'application indique à l'agent : "Lorsque tu me confies une tâche, fournis-moi également le nom et les métadonnées d'une action que je peux utiliser pour t'indiquer que cette tâche est terminée." L'application invoquera ensuite cette action lorsque l'utilisateur appuiera sur une case à cocher.

Ajoutez ensuite des champs required au schéma. Elles indiquent à l'agent de renseigner certaines propriétés à chaque fois. Dans ce cas, toutes les propriétés sont obligatoires.

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'],
);

Créer des classes d'analyse des données

Lors de la création d'instances de ce composant, l'agent envoie des données correspondant au schéma. Ajoutez deux classes pour analyser ce JSON entrant dans des objets Dart fortement typés. Notez que _TaskDisplayData gère la structure racine, tout en déléguant l'analyse du tableau interne à _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');
    }
  }
}

Si vous avez déjà utilisé Flutter, ces classes sont probablement semblables à celles que vous avez créées. Elles acceptent un JsonMap et renvoient un objet fortement typé contenant les données analysées à partir du JSON.

Examinez les champs actionName et actionContext dans _TaskData. Elles sont extraites de la propriété completeAction du fichier JSON et contiennent le nom de l'action et son contexte de données (une référence à l'emplacement de l'action dans le modèle de données de GenUI). Elles seront utilisées ultérieurement pour créer un UserActionEvent.

Le modèle de données est un magasin centralisé et observable pour tous les états d'UI dynamiques, géré par la bibliothèque genui. Lorsque l'agent crée un composant d'interface utilisateur à partir du catalogue, il crée également un objet de données correspondant au schéma du composant. Cet objet de données est stocké dans le modèle de données du client. Il peut donc être utilisé pour créer des widgets et être référencé dans les messages ultérieurs envoyés à l'agent (comme le completeAction que vous allez connecter à un widget).

Ajoutez le widget

Créez maintenant un widget pour afficher la liste. Elle doit accepter une instance de la classe _TaskDisplayData et un rappel à appeler lorsqu'une tâche est terminée.

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);
                    }
                  },
          ),
        ),
      ],
    );
  }
}

Créer l'élément CatalogItem

Une fois le schéma, l'analyseur et le widget créés, vous pouvez maintenant créer un CatalogItem pour les lier tous ensemble.

En bas de task_display.dart, créez taskDisplay en tant que variable de niveau supérieur, utilisez _TaskDisplayData pour analyser le JSON entrant et créez une instance du widget _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!
      },
    );
  },
);

Implémenter onCompleteTask

Pour que le widget fonctionne, il doit communiquer avec l'agent lorsqu'une tâche est terminée. Remplacez l'espace réservé onCompleteTask vide par le code suivant pour créer et envoyer un événement à l'aide de completeAction à partir des données de la tâche.

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,
    ),
  );
}

Enregistrer un élément de catalogue

Enfin, ouvrez main.dart, importez le nouveau fichier et enregistrez-le avec les autres éléments du catalogue.

Ajoutez cette importation en haut de lib/main.dart :

import 'task_display.dart';

Remplacez catalog = BasicCatalogItems.asCatalog(); dans votre fonction initState() par :

// 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]);

Vous avez terminé ! Effectuez un redémarrage à chaud de l'application pour voir les modifications.

8. Testez différentes façons d'interagir avec l'agent.

Une application de liste de tâches exécutée dans Chrome

Maintenant que vous avez ajouté le nouveau widget au catalogue et créé un espace pour celui-ci dans l'UI de l'application, il est temps de vous amuser avec l'agent. L'un des principaux avantages de GenUI est qu'il offre deux façons d'interagir avec vos données : via l'UI de l'application, comme les boutons et les cases à cocher, et via un agent qui comprend le langage naturel et peut raisonner sur les données. Essayez les deux !

  • Utilisez le champ de texte pour décrire trois ou quatre tâches, et regardez-les apparaître dans la liste.
  • Utilisez une case à cocher pour marquer une tâche comme terminée ou incomplète.
  • Créez une liste de cinq ou six tâches, puis demandez à l'agent de supprimer celles qui nécessitent de se déplacer.
  • Demandez à l'agent de créer une liste de tâches répétitives sous forme d'éléments individuels ("Je dois acheter une carte de vœux pour maman, papa et mamie. Crée des tâches distinctes pour cela.").
  • Dites à l'agent de marquer toutes les tâches comme terminées ou non terminées, ou de cocher les deux ou trois premières.

9. Félicitations

Félicitations ! Vous avez créé une application de suivi des tâches optimisée par l'IA à l'aide de l'UI générative et de Flutter.

Connaissances acquises

  • Interagir avec les modèles de fondation de Google à l'aide du SDK Flutter Firebase
  • Afficher des surfaces interactives générées par Gemini à l'aide de GenUI
  • Épingler des surfaces dans des mises en page à l'aide d'ID de rendu statiques prédéterminés
  • Concevoir des schémas et des catalogues de widgets personnalisés pour des boucles d'interaction robustes

Documents de référence