Tworzenie aplikacji z generatywnym interfejsem (GenUI)

1. Wprowadzenie

W tym ćwiczeniu utworzysz aplikację z listą zadań przy użyciu Fluttera, Firebase AI Logic i nowego pakietu genui. Zaczniesz od aplikacji do obsługi czatu tekstowego, ulepszysz ją za pomocą GenUI, aby umożliwić agentowi tworzenie własnego interfejsu, a na koniec utworzysz własny, niestandardowy, interaktywny komponent interfejsu, którym Ty i agent będziecie mogli bezpośrednio manipulować.

Aplikacja z listą zadań działająca w Chrome

Jakie zadania wykonasz

  • Tworzenie podstawowego interfejsu czatu za pomocą Fluttera i Firebase AI Logic
  • Zintegruj pakiet genui, aby generować powierzchnie oparte na AI
  • Dodawanie paska postępu, który będzie wskazywać, kiedy aplikacja czeka na odpowiedź od agenta
  • Utwórz nazwaną platformę i wyświetl ją w wyznaczonym miejscu w interfejsie.
  • Tworzenie niestandardowego komponentu katalogu GenUI, który umożliwia kontrolowanie sposobu prezentowania zadań

Czego potrzebujesz

To ćwiczenie jest przeznaczone dla średnio zaawansowanych programistów Fluttera.

2. Zanim zaczniesz

Konfigurowanie projektu Flutter

  1. Jeśli jeszcze nie masz zainstalowanego lokalnie pakietu SDK Flutter, zainstaluj go.
  2. Otwórz terminal i uruchom polecenie flutter create, aby utworzyć nowy projekt:
    flutter create intro_to_genui
    cd intro_to_genui
    
  3. Dodaj do projektu we Flutterze niezbędne zależności:
    flutter pub add firebase_core firebase_ai genui json_schema_builder
    
    Ostateczna sekcja dependencies powinna wyglądać tak (numery wersji mogą się nieznacznie różnić):
    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. Uruchom flutter pub get, aby pobrać wszystkie pakiety.Jeśli pojawi się komunikat, że dostępne są nowsze wersje pakietów, możesz uruchomić flutter pub outdated, aby sprawdzić wersje, i flutter pub upgrade, aby zaktualizować zależności.

Konfigurowanie projektu w Firebase

  1. Zainstaluj interfejs wiersza poleceń Firebase, jeśli jeszcze nie został zainstalowany.
  2. Zaloguj się w Firebase za pomocą konta Google:
    firebase login
    
  3. Zainstaluj interfejs wiersza poleceń FlutterFire:
    dart pub global activate flutterfire_cli
    
  4. W katalogu projektu Flutter uruchom to polecenie, aby skonfigurować projekt Flutter do korzystania z Firebase:
    flutterfire configure
    
    To polecenie wykona te działania:
    1. zapyta, czy chcesz użyć dotychczasowego projektu w Firebase, czy utworzyć nowy projekt w Firebase. Kliknij Utwórz nowy projekt w Firebase.
    2. Zostaniesz poproszony(-a) o wybranie platformy (iOS, Android, sieć), na którą chcesz kierować aplikację Flutter. Na razie wybierz Sieć.

Polecenie flutterfire configure automatycznie tworzy projekt w Firebase i nową aplikację internetową Firebase w tym projekcie w Firebase. Następnie polecenie utworzy plik konfiguracyjny Firebase (firebase_options.dart) i automatycznie doda go do katalogu lib/ w projekcie Fluttera.

Pamiętaj, że aplikacja w tym ćwiczeniu działa tylko z pakietem Flutter SDK i przeglądarką Chrome zainstalowanymi na Twoim komputerze (czyli jest tworzona jako aplikacja internetowa). Ta aplikacja została jednak utworzona w Flutterze, więc będzie działać również na innych platformach. Po ukończeniu tego ćwiczenia spróbuj ponownie uruchomić polecenie flutterfire configure, aby dodać obsługę iOS, Androida lub innej platformy, a następnie ponownie skompiluj aplikację na tej platformie.

Więcej informacji znajdziesz w instrukcjach dodawania Firebase do aplikacji Flutter.

Konfigurowanie Firebase AI Logic

  1. Zaloguj się w konsoli Firebase. Użyj tego samego konta Google, którego używasz do logowania się w interfejsie wiersza poleceń Firebase.
  2. Wybierz projekt w Firebase, który został utworzony za pomocą interfejsu wiersza poleceń FlutterFire.
  3. W menu nawigacyjnym po lewej stronie wybierz AI Services > AI Logic (Usługi AI > Logika AI).
  4. Aby uruchomić proces z pomocą przewodnika, kliknij Rozpocznij.
  5. Wybierz opcję rozpoczęcia od Gemini Developer API i postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby skonfigurować Firebase AI Logic.

Masz już wymagane wtyczki FlutterFire do korzystania z Firebase AI Logic z sekcji „Konfigurowanie projektu Flutter”. W następnym kroku możesz już zacząć kodować aplikację.

3. Tworzenie podstawowego interfejsu czatu

Zanim wprowadzisz generatywny interfejs, Twoja aplikacja musi mieć podstawę: prostą aplikację do czatu tekstowego opartą na Firebase AI Logic. Aby szybko rozpocząć, skopiujesz i wkleisz całą konfigurację interfejsu czatu.

wersję aplikacji opartą na tekście,

Tworzenie widżetu dymka wiadomości

Aby wyświetlać SMS-y od użytkownika i agenta, aplikacja potrzebuje widżetu. Utwórz nowy plik o nazwie lib/message_bubble.dart i dodaj tę klasę:

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 to StatelessWidget, który wyświetla pojedynczą wiadomość na czacie. Będzie on używany w dalszej części tego ćwiczenia do wyświetlania wiadomości od Ciebie i od agenta, ale jest to w zasadzie tylko zaawansowany widżet Text.

Wdrażanie interfejsu czatu w main.dart

Zastąp całą zawartość pliku lib/main.dart tą pełną implementacją tekstowego chatbota:

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

Skopiowany i wklejony plik main.dart konfiguruje podstawową funkcję ChatSession przy użyciu Firebase AI Logic i prompta w pliku systemInstruction. Zarządza kolejnymi etapami rozmowy, utrzymując listę elementów TextItem i wyświetlając je obok zapytań użytkownika za pomocą utworzonego wcześniej widżetu MessageBubble.

Zanim przejdziesz dalej, sprawdź te kwestie:

  • Metoda initState służy do konfigurowania połączenia z Firebase AI Logic.
  • Aplikacja zawiera TextField i przycisk do wysyłania wiadomości do agenta.
  • Metoda _addMessage polega na wysłaniu wiadomości użytkownika do agenta.
  • Historia rozmów jest przechowywana na liście _items.
  • Wiadomości są wyświetlane w ListView za pomocą widżetu MessageBubble.

Testowanie aplikacji

Po dodaniu kodu możesz uruchomić aplikację i ją przetestować.

flutter run -d chrome

Spróbuj porozmawiać z agentem o zadaniach, które chcesz dziś wykonać. Czysto tekstowy interfejs użytkownika może spełniać swoje zadanie, ale GenUI może ułatwić i przyspieszyć korzystanie z aplikacji.

Po zakończeniu testowania zatrzymaj działającą aplikację, naciskając q (lub Ctrl+C) w terminalu, zanim przejdziesz do następnego kroku.

4. Integracja pakietu GenUI

Teraz możesz przejść ze zwykłego tekstu na interfejs generatywny. Podstawową pętlę wiadomości Firebase zastąpisz obiektami GenUI Conversation, Catalog i SurfaceController. Dzięki temu model AI może tworzyć rzeczywiste widżety Fluttera w strumieniu czatu.

Wersja aplikacji z zintegrowanym generatywnym interfejsem użytkownika

Pakiet genui zawiera 5 klas, których będziesz używać w tym ćwiczeniu:

  • SurfaceController mapuje interfejs wygenerowany przez model na ekran.
  • A2uiTransportAdapter łączy wewnętrzne żądania GenUI z dowolnym zewnętrznym modelem językowym.
  • Conversation opakowuje kontroler i adapter transportu w jeden ujednolicony interfejs API dla aplikacji Flutter.
  • Catalog opisuje widżety i właściwości dostępne dla modelu językowego.
  • Surface to widżet, który wyświetla interfejs wygenerowany przez model.

Przygotuj się do wyświetlenia wygenerowanego elementu Surface

W pliku lib/main.dart dotychczasowy kod zawiera klasę TextItem, która reprezentuje pojedynczą wiadomość tekstową w rozmowie. Bezpośrednio po klasie TextItem dodaj klasę SurfaceItem, aby reprezentować Surface utworzony przez agenta:

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

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

Inicjowanie elementów składowych GenUI

U góry pliku lib/main.dart zaimportuj bibliotekę genui:

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

Zarówno pakiet genui, jak i pakiet firebase_ai zawierają klasę TextPart. Importując genui w ten sposób, tworzysz przestrzeń nazw dla jego wersji TextPart jako genui.TextPart, co pozwala uniknąć konfliktu nazw.

Zadeklaruj podstawowe kontrolery funkcji w pliku _MyHomePageState po _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;

Następnie zaktualizuj plik initState, aby przygotować kontrolery biblioteki GenUI.

Usuń ten wiersz z pliku initState:

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

Następnie dodaj ten kod:

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

Ten kod tworzy fasadę Conversation, która zarządza kontrolerem i adapterem. Ta rozmowa zapewnia aplikacji strumień zdarzeń, których może używać do śledzenia tego, co tworzy agent, a także metodę wysyłania do niego wiadomości.

Następnie utwórz detektor zdarzeń rozmowy. Obejmują one zdarzenia związane z powierzchnią, a także zdarzenia dotyczące SMS-ów i błędów:

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

Na koniec utwórz prompt systemowy i wyślij go do agenta:

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

Zaktualizuj też metodę dispose() w pliku _MyHomePageState, aby nowo dodane kontrolery GenUI były prawidłowo czyszczone po usunięciu widżetu:

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

Platformy wyświetlania

Następnie zaktualizuj metodę build klasy ListView, aby wyświetlać obiekty SurfaceItem na liście _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,
            ),
          ),
        },
    ],
  ),
),

Konstruktor widżetu Surface pobiera surfaceContext, który informuje go, za wyświetlanie której powierzchni odpowiada. Utworzony wcześniej obiekt SurfaceController, _controller, zawiera definicję i stan każdej powierzchni oraz dba o to, aby została ona ponownie utworzona po aktualizacji.

Łączenie GenUI z Firebase AI Logic

Pakiet genui korzysta z podejścia „Bring Your Own Model” (BYOM), co oznacza, że to Ty decydujesz, który model LLM będzie obsługiwać Twoje działania. W tym przypadku używasz Firebase AI Logic, ale pakiet został stworzony do współpracy z różnymi agentami i dostawcami.

Ta swoboda wiąże się z dodatkową odpowiedzialnością: musisz pobierać wiadomości wygenerowane przez pakiet genui i wysyłać je do wybranego agenta, a także pobierać odpowiedzi agenta i wysyłać je z powrotem do pakietu genui.

W tym celu zdefiniujesz metodę _sendAndReceive, do której odwołuje się kod z poprzedniego kroku. W pliku lib/main.dart dodaj _sendAndReceive w klasie _MyHomePageState (na przykład zaraz po wierszu 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!);
    }
  }

Ta metoda będzie wywoływana przez pakiet genui, gdy będzie on musiał wysłać wiadomość do agenta. Wywołanie addChunk na końcu metody przekazuje odpowiedź agenta z powrotem do pakietu genui, co umożliwia mu przetworzenie odpowiedzi i wygenerowanie interfejsu.

Na koniec zastąp całkowicie dotychczasową metodę _addMessage tą nową wersją, aby kierowała wiadomości do Conversation, a nie bezpośrednio do 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));
  }

To wszystko. Spróbuj ponownie uruchomić aplikację. Oprócz wiadomości tekstowych zobaczysz, jak agent generuje elementy interfejsu, takie jak przyciski, widżety tekstowe i inne.

Możesz nawet poprosić agenta o wyświetlenie interfejsu w określony sposób. Możesz na przykład wpisać „Pokaż mi moje zadania w kolumnie z przyciskiem oznaczania każdego z nich jako ukończonego”.

5. Dodawanie stanu oczekiwania

Generowanie LLM jest asynchroniczne. Podczas oczekiwania na odpowiedź interfejs czatu musi wyłączyć przyciski wprowadzania i wyświetlić wskaźnik postępu, aby użytkownik wiedział, że GenUI tworzy treści. Na szczęście pakiet genui zawiera Listenable, którego możesz użyć do śledzenia stanu rozmowy. Ta wartość ConversationState zawiera właściwość isWaiting, która określa, czy model generuje treści.

Umieść elementy sterujące w elemencie ValueListenableBuilder.

W metodzie build klasy _MyHomePageState w pliku lib/main.dart znajdź widżet SafeArea u dołu Column i opakuj jego element podrzędny Row (który zawiera TextField i ElevatedButton) w ValueListenableBuilder, który nasłuchuje _conversation.state. Sprawdzając state.isWaiting, możesz wyłączyć wprowadzanie danych, gdy model generuje treści:

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

Dodawanie paska postępu

W metodzie build klasy _MyHomePageState umieść główny widżet Column w widżecie Stack i dodaj widżet ValueListenableBuilder, który renderuje widżet LinearProgressIndicator jako drugi element podrzędny widżetu Stack. Gdy skończysz, body Twojego Scaffold powinien wyglądać tak:

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. Trwałe przechowywanie interfejsu GenUI

Do tej pory lista zadań była renderowana na przewijanym czacie, a każda nowa wiadomość lub powierzchnia była dodawana do listy w miarę jej pojawiania się. W następnym kroku dowiesz się, jak nazwać powierzchnię i wyświetlić ją w określonym miejscu w interfejsie.

Najpierw u góry pliku lib/main.dart, przed void main(), zadeklaruj stałą, która będzie używana jako identyfikator platformy:

const taskDisplaySurfaceId = 'task_display';

Po drugie, w pliku initState() zaktualizuj instrukcję switch w detektorze Conversation, aby upewnić się, że żadna platforma o tym identyfikatorze nie zostanie dodana do _items. Aby to zrobić, zaktualizuj gałąź case ConversationSurfaceAdded added: w pliku _conversation.events.listen, umieszczając wiersze _items.add(...) i _scrollToBottom() w instrukcji 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 ...

Następnie otwórz strukturę układu drzewa widżetów w _MyHomePageState.build, aby utworzyć miejsce na przypiętą powierzchnię bezpośrednio przed dziennikiem czatu. Wstaw AnimatedSize i const Divider() jako 2 pierwsze elementy podrzędne głównego elementu Column, tuż przed kodem 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 ...

Do tej pory agent miał pełną swobodę tworzenia i używania platform według własnego uznania. Aby podać mu bardziej szczegółowe instrukcje, musisz wrócić do prompta systemowego. Dodaj tę sekcję ## USER INTERFACE na końcu prompta zapisanego w stałej 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.
''';

Ważne jest, aby przekazać agentowi jasne instrukcje dotyczące tego, kiedy i jak korzystać z interfejsu. Jeśli powiesz agentowi, aby użył konkretnego elementu katalogu i identyfikatora platformy (oraz aby ponownie użył pojedynczej instancji), możesz mieć pewność, że utworzy on interfejs, który chcesz zobaczyć.

Jest jeszcze trochę pracy do wykonania, ale możesz spróbować ponownie uruchomić aplikację, aby zobaczyć, jak agent tworzy obszar wyświetlania zadania u góry interfejsu.

7. Tworzenie własnego widżetu katalogu

W tym momencie produkt TaskDisplay nie istnieje. W kilku następnych krokach naprawisz ten problem, tworząc schemat danych, klasę do jego analizowania, widżet i element katalogu, który łączy wszystkie te elementy.

Najpierw utwórz nowy plik o nazwie task_display.dart w katalogu lib/ projektu i dodaj te instrukcje importu:

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

Tworzenie schematu danych

Następnie zdefiniuj schemat danych, który agent będzie dostarczać, gdy będzie chciał utworzyć wyświetlanie zadania. Proces ten wykorzystuje kilka zaawansowanych konstruktorów z pakietu json_schema_builder, ale w zasadzie definiujesz tylko schemat JSON używany w wiadomościach wysyłanych do agenta i przez niego.

Zacznij od podstawowego elementu S.object odwołującego się do nazwy komponentu:

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

Następnie dodaj do właściwości schematu elementy title, tasks, name, isCompleted i 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.',
          ),
        },
      ),
    ),
  },
);

Sprawdź właściwość completeAction. Jest on tworzony za pomocą funkcji A2uiSchemas.action, konstruktora właściwości schematu, który reprezentuje działanie A2UI. Dodając działanie do schematu, aplikacja zasadniczo informuje agenta: „Gdy dajesz mi zadanie, podaj też nazwę i metadane działania, którego mogę użyć, aby poinformować Cię, że zadanie zostało wykonane”. Później aplikacja wywoła to działanie, gdy użytkownik kliknie pole wyboru.

Następnie dodaj do schematu pola required. Instruują one agenta, aby za każdym razem wypełniał określone właściwości. W takim przypadku wymagane są wszystkie właściwości.

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

Tworzenie klas analizowania danych

Podczas tworzenia instancji tego komponentu agent będzie wysyłać dane zgodne ze schematem. Dodaj 2 klasy, aby przeanalizować przychodzący kod JSON i przekształcić go w obiekty Dart o ściśle określonym typie. Zwróć uwagę, jak _TaskDisplayData obsługuje strukturę główną, a parsowanie tablicy wewnętrznej przekazuje do _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');
    }
  }
}

Jeśli masz już doświadczenie z Flutterem, te klasy są prawdopodobnie podobne do tych, które zostały przez Ciebie utworzone. Akceptują one obiekt JsonMap i zwracają obiekt o silnym typie zawierający dane przeanalizowane z JSON.

Przyjrzyj się polom actionName i actionContext w _TaskData. Są one wyodrębniane z właściwości completeAction pliku JSON i zawierają nazwę działania oraz jego kontekst danych (odniesienie do lokalizacji działania w modelu danych GenUI). Zostaną one później użyte do utworzenia UserActionEvent.

Model danych to scentralizowany, możliwy do obserwowania magazyn wszystkich dynamicznych stanów interfejsu, który jest obsługiwany przez bibliotekę genui. Gdy agent tworzy komponent interfejsu z katalogu, tworzy też obiekt danych zgodny ze schematem komponentu. Ten obiekt danych jest przechowywany w modelu danych w kliencie, dzięki czemu można go używać do tworzenia widżetów i odwoływać się do niego w późniejszych wiadomościach do agenta (takich jak completeAction, który zaraz połączysz z widżetem).

Dodaj widżet

Teraz utwórz widżet, który będzie wyświetlać listę. Powinna ona akceptować instancję klasy _TaskDisplayData i wywołanie zwrotne, które ma zostać wywołane po zakończeniu zadania.

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

Tworzenie elementu CatalogItem

Po utworzeniu schematu, parsera i widżetu możesz teraz utworzyć CatalogItem, aby je połączyć.

U dołu funkcji task_display.dart utwórz zmienną najwyższego poziomu taskDisplay, użyj funkcji _TaskDisplayData, aby przeanalizować przychodzący kod JSON, i utwórz instancję widżetu _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!
      },
    );
  },
);

Implementacja onCompleteTask

Aby widżet działał, musi poinformować agenta o zakończeniu zadania. Zastąp pusty obiekt zastępczy onCompleteTask poniższym kodem, aby utworzyć i wysłać zdarzenie za pomocą completeAction z danych zadania.

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

Rejestrowanie produktu z katalogu

Na koniec otwórz main.dart, zaimportuj nowy plik i zarejestruj go wraz z innymi elementami katalogu.

Dodaj ten import na początku pliku lib/main.dart:

import 'task_display.dart';

Zastąp catalog = BasicCatalogItems.asCatalog(); w funkcji initState() tym kodem:

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

To już wszystko. Aby zobaczyć zmiany, uruchom ponownie aplikację.

8. Eksperymentuj z różnymi sposobami interakcji z agentem.

Aplikacja z listą zadań działająca w Chrome

Po dodaniu nowego widżetu do katalogu i utworzeniu dla niego miejsca w interfejsie aplikacji możesz zacząć pracę z agentem. Jedną z głównych zalet GenUI jest to, że oferuje 2 sposoby interakcji z danymi: za pomocą interfejsu aplikacji, np. przycisków i pól wyboru, oraz za pomocą agenta, który rozumie język naturalny i może analizować dane. Wypróbuj oba te sposoby.

  • Wpisz w polu tekstowym 3–4 zadania i obserwuj, jak pojawiają się na liście.
  • Użyj pola wyboru, aby oznaczyć zadanie jako ukończone lub nieukończone.
  • Utwórz listę 5–6 zadań, a następnie poproś agenta o usunięcie tych, które wymagają dojazdu.
  • Poproś agenta o utworzenie powtarzalnej listy zadań jako poszczególnych elementów („Muszę kupić kartkę świąteczną dla mamy, taty i babci. Utwórz dla nich osobne zadania”).
  • Poproś agenta o oznaczenie wszystkich zadań jako ukończonych lub nieukończonych albo o zaznaczenie pierwszych 2–3 zadań.

9. Gratulacje

Gratulacje! Udało Ci się utworzyć aplikację do śledzenia zadań opartą na AI, która korzysta z generatywnego interfejsu i Fluttera.

Czego się nauczysz

  • Interakcja z modelami podstawowymi Google za pomocą pakietu Flutter Firebase SDK
  • Renderowanie interaktywnych interfejsów wygenerowanych przez Gemini za pomocą GenUI
  • przypinanie platform w układach za pomocą wstępnie określonych statycznych identyfikatorów renderowania;
  • projektowanie niestandardowych schematów i katalogów widżetów na potrzeby solidnych pętli interakcji;

Dokumentacja referencyjna