פיתוח אפליקציית ממשק משתמש גנרטיבי (GenUI)

1. מבוא

ב-Codelab הזה, תיצרו אפליקציה של רשימת משימות באמצעות Flutter,‏ Firebase AI Logic והחבילה החדשה genui. מתחילים עם אפליקציית צ'אט מבוססת-טקסט, משדרגים אותה באמצעות GenUI כדי לתת לסוכן את היכולת ליצור ממשק משתמש משלו, ולבסוף יוצרים רכיב ממשק משתמש אינטראקטיבי בהתאמה אישית שאתם והסוכן יכולים לשנות ישירות.

אפליקציה של רשימת משימות שפועלת ב-Chrome

הפעולות שתבצעו:

  • יצירת ממשק צ'אט בסיסי באמצעות Flutter ו-Firebase AI Logic
  • שילוב חבילת genui ליצירת ממשקים מבוססי-AI
  • הוספת סרגל התקדמות שמציין מתי האפליקציה ממתינה לתשובה מהנציג
  • ליצור משטח עם שם ולהציג אותו במקום ייעודי בממשק המשתמש.
  • ליצור רכיב קטלוג מותאם אישית של GenUI שמאפשר לכם לשלוט באופן שבו המשימות מוצגות

הדרישות

שיעור ה-Codelab הזה מיועד למפתחי 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 CLI.
  2. מתחברים ל-Firebase באמצעות חשבון Google:
    firebase login
    
  3. מתקינים את FlutterFire CLI:
    dart pub global activate flutterfire_cli
    
  4. מריצים את הפקודה הבאה מתיקיית הפרויקט של Flutter כדי להגדיר את הפרויקט של Flutter לשימוש ב-Firebase:
    ‫
    flutterfire configure
    
    הפקודה הזו תבצע את הפעולות הבאות:
    1. האם רוצים להשתמש בפרויקט Firebase קיים או ליצור פרויקט Firebase חדש. בוחרים באפשרות יצירת פרויקט חדש ב-Firebase.
    2. תופיע בקשה לבחור את הפלטפורמה (iOS, ‏ Android, אינטרנט) שבה רוצים להפעיל את אפליקציית Flutter. בשלב הזה, בוחרים באפשרות Web.

הפקודה flutterfire configure יוצרת באופן אוטומטי פרויקט ב-Firebase ואפליקציית אינטרנט חדשה ב-Firebase באותו פרויקט. הפקודה יוצרת קובץ הגדרות של Firebase ‏ (firebase_options.dart) ומוסיפה אותו באופן אוטומטי לספרייה lib/ של פרויקט Flutter.

שימו לב שהאפליקציה ב-Codelab הזה פועלת רק עם Flutter SDK ו-Chrome שמותקנים במחשב (כלומר, היא נוצרת כאפליקציית אינטרנט). אבל מכיוון שהאפליקציה הזו פותחה באמצעות Flutter, היא תפעל גם בפלטפורמות אחרות. לכן, בסוף שיעור ה-Codelab, כדאי להריץ מחדש את flutterfire configure כדי להוסיף תמיכה ב-iOS, ב-Android או בפלטפורמה אחרת, ואז לבנות מחדש את האפליקציה בפלטפורמה הזו.

מידע נוסף זמין בהוראות להוספת Firebase לאפליקציית Flutter.

הגדרת Firebase AI Logic

  1. נכנסים למסוף Firebase. משתמשים באותו חשבון Google שבו השתמשתם כדי להתחבר ל-Firebase CLI.
  2. בוחרים את הפרויקט ב-Firebase שיצרתם באמצעות FlutterFire CLI.
  3. בתפריט הניווט הימני, לוחצים על שירותי AI‏ > 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 שמציג הודעת צ'אט אחת. נשתמש בו בהמשך ה-Codelab הזה כדי להציג הודעות גם מכם וגם מהסוכן, אבל הוא בעיקר ווידג'ט 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

אפשר לנסות לשוחח עם הסוכן על כמה משימות שרוצים לבצע היום. ממשק משתמש שמבוסס רק על טקסט יכול לעשות את העבודה, אבל ממשק משתמש גנרטיבי יכול להפוך את החוויה לקלה ומהירה יותר.

אחרי שמסיימים את הבדיקה, עוצרים את האפליקציה שפועלת על ידי לחיצה על q (או Ctrl+C) במסוף לפני שממשיכים לשלב הבא.

4. שילוב חבילת GenUI

עכשיו הגיע הזמן לשדרג מטקסט פשוט לממשק משתמש גנרטיבי. תחליפו את לולאת ההודעות הבסיסית של Firebase באובייקטים של GenUI מסוג Conversation,‏ Catalog ו-SurfaceController. כך מודל ה-AI יכול ליצור מופעים של ווידג'טים אמיתיים של Flutter בסטרימינג של הצ'אט.

גרסה של האפליקציה עם ממשק משתמש גנרטיבי משולב

החבילה genui מספקת חמש מחלקות שבהן תשתמשו ב-Codelab הזה:

  • SurfaceController ממשק המשתמש של מפות Google שנוצר על ידי המודל למסך.
  • ‫A2uiTransportAdapter מקשר בין בקשות פנימיות של GenUI לבין כל מודל שפה חיצוני.
  • ‫Conversation עוטף את הבקר ואת מתאם ההעברה ב-API אחד מאוחד לאפליקציית Flutter.
  • ‫Catalog מתאר את הווידג'טים והמאפיינים שזמינים למודל השפה.
  • ‫Surface הוא ווידג'ט שמציג ממשק משתמש שנוצר על ידי המודל.

מכינים את הקרקע להצגת Surface שנוצר על ידי AI

ב-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's build כדי להציג את SurfaceItems ברשימה _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 בסוף ה-method מזינה את התשובה של הנציג בחזרה לחבילת 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));
  }

זהו! מנסים להפעיל שוב את האפליקציה. בנוסף להודעות SMS, תראו שהסוכן יוצר ממשקי משתמש כמו לחצנים, ווידג'טים של טקסט ועוד.

אתם יכולים אפילו לבקש מהסוכן להציג את ממשק המשתמש בצורה מסוימת. לדוגמה, אפשר לנסות הודעה כמו "תציג לי את המשימות שלי בעמודה, עם לחצן לסימון כל אחת מהן כהושלמה".

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

הוספת סרגל התקדמות

ב-method‏ 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, ה-constructor של מאפיין סכימה שמייצג פעולת 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 וקריאה חוזרת (callback) שתופעל כשהמשימה תושלם.

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

כדי שהווידג'ט יפעל, הוא צריך לתקשר עם הנציג כשהמשימה מסתיימת. מחליפים את ה-placeholder הריק 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. מזל טוב

מעולה! יצרתם אפליקציה למעקב אחרי משימות שמבוססת על AI באמצעות ממשק משתמש גנרטיבי ו-Flutter.

מה למדתם

  • אינטראקציה עם המודלים הבסיסיים של Google באמצעות Flutter Firebase SDK
  • עיבוד של פלטפורמות אינטראקטיביות שנוצרו על ידי Gemini באמצעות GenUI
  • הצמדת משטחים בפריסות באמצעות מזהי רינדור סטטיים שנקבעו מראש
  • תכנון סכימות בהתאמה אישית וקטלוגים של ווידג'טים ליצירת לולאות אינטראקציה חזקות

מסמכי עזר