1. Introduzione
In questo codelab creerai un'app di elenco attività utilizzando Flutter, Firebase AI Logic e il nuovo pacchetto genui. Inizierai con un'app di chat basata su testo, la aggiornerai con GenUI per dare all'agente la possibilità di creare la propria UI e infine creerai il tuo componente UI personalizzato e interattivo che tu e l'agente potrete manipolare direttamente.

In questo lab proverai a:
- Crea un'interfaccia di chat di base utilizzando Flutter e Firebase AI Logic
- Integra il pacchetto
genuiper generare superfici basate sull'AI generativa - Aggiungi una barra di avanzamento per indicare quando l'app è in attesa di una risposta da parte dell'agente
- Crea una superficie denominata e mostrala in una posizione dedicata nella UI.
- Crea un componente del catalogo GenUI personalizzato che ti consente di controllare il modo in cui vengono presentate le attività
Che cosa ti serve
- Un browser web, ad esempio Chrome
- L'SDK Flutter installato localmente
- L'interfaccia a riga di comando di Firebase installata e configurata
Questo codelab è rivolto a sviluppatori Flutter di livello intermedio.
2. Prima di iniziare
Configura il progetto Flutter
- Se non l'hai ancora fatto, installa l'SDK Flutter localmente.
- Apri il terminale ed esegui
flutter createper creare un nuovo progetto:flutter create intro_to_genui cd intro_to_genui - Aggiungi le dipendenze necessarie al tuo progetto Flutter:
La sezioneflutter pub add firebase_core firebase_ai genui json_schema_builderdependenciesfinale dovrebbe essere simile alla seguente (i numeri di versione potrebbero variare leggermente):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 - Esegui
flutter pub getper scaricare tutti i pacchetti.Se ti viene comunicato che sono disponibili versioni più recenti dei pacchetti, puoi eseguireflutter pub outdatedper controllare le versioni eflutter pub upgradeper aggiornare le dipendenze.
Configura un progetto Firebase
- Se non l'hai ancora fatto, installa l'interfaccia a riga di comando di Firebase.
- Accedi a Firebase utilizzando il tuo Account Google:
firebase login - Installa l'interfaccia a riga di comando FlutterFire:
dart pub global activate flutterfire_cli - Dalla directory del progetto Flutter, esegui questo comando per configurare il progetto Flutter in modo che utilizzi Firebase:
Questo comando esegue le seguenti operazioni:flutterfire configure- Ti verrà chiesto se vuoi utilizzare un progetto Firebase esistente o crearne uno nuovo. Seleziona Crea un nuovo progetto Firebase.
- Ti verrà chiesto quale piattaforma (iOS, Android, Web) vuoi scegliere come target per la tua app Flutter. Per il momento, seleziona Web.
Il comando flutterfire configure crea automaticamente un progetto Firebase e una nuova app web Firebase al suo interno. Il comando crea quindi un file di configurazione Firebase (firebase_options.dart) e lo aggiunge automaticamente alla directory lib/ del tuo progetto Flutter.
Tieni presente che l'app per questo codelab funziona solo con l'SDK Flutter e Chrome installati sul tuo computer (ovvero, viene creata come app web). Tuttavia, poiché questa app è creata con Flutter, funzionerà anche su altre piattaforme. Quindi, alla fine del codelab, prova a eseguire di nuovo flutterfire configure per aggiungere il supporto per iOS, Android o un'altra piattaforma, quindi ricrea l'app su quella piattaforma.
Per saperne di più, consulta le istruzioni per aggiungere Firebase a un'app Flutter.
Configura Firebase AI Logic
- Accedi alla console Firebase. Utilizza lo stesso Account Google che hai utilizzato per accedere all'interfaccia a riga di comando di Firebase.
- Seleziona il progetto Firebase che hai appena creato utilizzando l'interfaccia a riga di comando FlutterFire.
- Nel menu di navigazione a sinistra, seleziona Servizi AI > AI Logic.
- Fai clic su Inizia per avviare il flusso di lavoro guidato.
- Seleziona l'API Gemini Developer per iniziare e segui i messaggi sullo schermo per configurare Firebase AI Logic.
Hai già i plug-in FlutterFire necessari per utilizzare Firebase AI Logic dalla sezione "Configura un progetto Flutter". Ora puoi passare alla programmazione della tua app nel passaggio successivo.
3. Crea un'interfaccia di chat di base
Prima di introdurre la UI generativa, la tua app ha bisogno di una base: un'applicazione di chat di base basata su testo e su Firebase AI Logic. Per iniziare rapidamente, copia e incolla l'intera configurazione per l'interfaccia di chat.

Creare il widget della bolla del messaggio
Per visualizzare i messaggi dell'utente e dell'agente, la tua app ha bisogno di un widget. Crea un nuovo file denominato lib/message_bubble.dart e aggiungi la seguente classe:
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 è un StatelessWidget che mostra un singolo messaggio chat. Verrà utilizzato più avanti in questo codelab per mostrare i messaggi inviati da te e dall'agente, ma si tratta principalmente di un widget Text elaborato.
Implementare l'UI di Chat in main.dart
Sostituisci l'intero contenuto di lib/main.dart con questa implementazione completa della chatbot di testo:
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.
''';
Il file main.dart che hai appena copiato e incollato configura un ChatSession di base utilizzando Firebase AI Logic e il prompt in systemInstruction. Gestisce i turni di conversazione mantenendo un elenco di elementi TextItem e visualizzandoli insieme alle query degli utenti utilizzando il widget MessageBubble che hai creato in precedenza.
Ecco alcuni aspetti da verificare prima di procedere:
- Il metodo
initStateè il punto in cui viene configurata la connessione a Firebase AI Logic. - L'app offre un
TextFielde un pulsante per inviare messaggi all'agente. - Il metodo
_addMessageprevede l'invio del messaggio dell'utente all'agente. - L'elenco
_itemsè il luogo in cui viene archiviata la cronologia delle conversazioni. - I messaggi vengono visualizzati in un
ListViewutilizzando il widgetMessageBubble.
Testa l'app
Ora puoi eseguire l'app e testarla.
flutter run -d chrome
Prova a parlare con l'agente di alcune attività che vorresti svolgere oggi. Anche se un'interfaccia utente basata esclusivamente su testo può svolgere il lavoro, GenUI può rendere l'esperienza più semplice e veloce.
Al termine del test, interrompi l'app in esecuzione premendo q (o Ctrl+C) nel terminale prima di procedere al passaggio successivo.
4. Integra il pacchetto GenUI
Ora è il momento di passare dal testo normale alla UI generativa. Sostituirai il ciclo di messaggistica Firebase di base con gli oggetti GenUI Conversation, Catalog e SurfaceController. In questo modo, il modello di AI può creare istanze di widget Flutter effettivi all'interno dello stream della chat.

Il pacchetto genui fornisce cinque classi che utilizzerai in questo codelab:
SurfaceControllermappa la UI generata dal modello sullo schermo.A2uiTransportAdaptercollega le richieste GenUI interne a qualsiasi modello linguistico esterno.Conversationunisce il controller e l'adattatore di trasporto in un'unica API unificata per la tua app Flutter.Catalogdescrive i widget e le proprietà disponibili per il modello linguistico.Surfaceè un widget che mostra l'interfaccia utente generata dal modello.
Preparati a visualizzare un Surface generato
In lib/main.dart, il codice esistente include una classe TextItem che rappresenta un singolo messaggio all'interno della conversazione. Subito dopo la classe TextItem, aggiungi una classe SurfaceItem per rappresentare un Surface creato dall'agente:
class TextItem extends ConversationItem {
// ... existing code ...
}
// New!
class SurfaceItem extends ConversationItem {
final String surfaceId;
SurfaceItem({required this.surfaceId});
}
Inizializza i componenti di base di GenUI
Nella parte superiore di lib/main.dart, importa la libreria genui:
import 'package:genui/genui.dart' hide TextPart;
import 'package:genui/genui.dart' as genui;
Sia il pacchetto genui che il pacchetto firebase_ai includono una classe TextPart. Importando genui in questo modo, assegni uno spazio dei nomi alla sua versione di TextPart come genui.TextPart, evitando una collisione di nomi.
Dichiara i controller funzionali principali in _MyHomePageState dopo _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;
Poi, aggiorna initState per preparare i controller della libreria GenUI.
Rimuovi questa riga da initState:
_chatSession.sendMessage(Content.text(systemInstruction));
Quindi, aggiungi il seguente codice:
@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,
);
}
Questo codice crea una facciata Conversation che gestisce il controller e l'adattatore. Questa conversazione offre alla tua app uno stream di eventi che può utilizzare per tenere il passo con ciò che l'agente sta creando, nonché un metodo per inviare messaggi all'agente.
Successivamente, crea un listener per gli eventi di conversazione. Sono inclusi eventi relativi alla superficie, nonché quelli per messaggi ed errori:
@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:
}
});
});
}
Infine, crea il prompt di sistema e invialo all'agente:
@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()),
);
}
Aggiorna anche il metodo dispose() in _MyHomePageState in modo che i controller GenUI appena aggiunti vengano puliti correttamente quando il widget viene eliminato:
@override
void dispose() {
_conversation.dispose();
_transport.dispose();
_controller.dispose();
_textController.dispose();
_scrollController.dispose();
super.dispose();
}
Superfici di visualizzazione
Poi, aggiorna il metodo build di ListView per visualizzare gli elementi SurfaceItem nell'elenco _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,
),
),
},
],
),
),
Il costruttore del widget Surface accetta un surfaceContext che indica la superficie che deve visualizzare. Il SurfaceController creato in precedenza, _controller, fornisce la definizione e lo stato di ogni superficie e si assicura che venga ricreata quando è disponibile un aggiornamento.
Collegare GenUI a Firebase AI Logic
Il pacchetto genui utilizza un approccio "Bring Your Own Model", il che significa che controlli quale LLM alimenta la tua esperienza. In questo caso, utilizzi Firebase AI Logic, ma il pacchetto è progettato per funzionare con una varietà di agenti e provider.
Questa libertà comporta un po' di responsabilità in più: devi prendere i messaggi generati dal pacchetto genui e inviarli all'agente che hai scelto, e devi prendere le risposte dell'agente e inviarle di nuovo a genui.
Per farlo, definirai il metodo _sendAndReceive a cui viene fatto riferimento nel codice per il passaggio precedente. In lib/main.dart, aggiungi _sendAndReceive all'interno della classe _MyHomePageState (ad esempio, subito dopo la riga 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!);
}
}
Questo metodo verrà chiamato dal pacchetto genui ogni volta che deve inviare un messaggio all'agente. La chiamata a addChunk alla fine del metodo invia la risposta dell'agente al pacchetto genui, consentendogli di elaborare la risposta e generare la UI.
Infine, sostituisci completamente il metodo _addMessage esistente con questa nuova versione, in modo che i messaggi vengano indirizzati a Conversation anziché direttamente a 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));
}
È tutto. Prova a eseguire di nuovo l'app. Oltre ai messaggi, vedrai l'agente generare elementi di UI come pulsanti, widget di testo e altro ancora.
Puoi anche provare a chiedere all'agente di visualizzare la UI in un modo particolare. Ad esempio, prova un messaggio come "Mostrami le mie attività in una colonna, con un pulsante per contrassegnare ciascuna come completata".
5. Aggiungi stato di attesa
La generazione di LLM è asincrona. Durante l'attesa di una risposta, l'interfaccia di chat deve disattivare i pulsanti di input e visualizzare un indicatore di avanzamento in modo che l'utente sappia che GenUI sta creando contenuti. Fortunatamente, il pacchetto genui fornisce un Listenable che puoi utilizzare per monitorare lo stato della conversazione. Questo valore ConversationState include una proprietà isWaiting per determinare se il modello sta generando contenuti.
Aggrega i controlli di input con un ValueListenableBuilder
Nel metodo build di _MyHomePageState in lib/main.dart, individua il widget SafeArea nella parte inferiore di Column e racchiudi il relativo elemento secondario Row (che contiene TextField e ElevatedButton) con un ValueListenableBuilder che ascolta _conversation.state. Esaminando state.isWaiting, puoi disattivare l'input mentre il modello genera i contenuti:
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'),
),
],
);
},
),
),
),
Aggiungi una barra di avanzamento
Nel metodo build di _MyHomePageState, racchiudi il widget Column principale all'interno di un Stack e aggiungi un ValueListenableBuilder che esegue il rendering di un LinearProgressIndicator come secondo elemento secondario di Stack. Al termine, il body del tuo Scaffold dovrebbe avere il seguente aspetto:
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. Rendi persistente una superficie GenUI
Finora, l'elenco di attività è stato visualizzato nel flusso di chat a scorrimento, con ogni nuovo messaggio o superficie aggiunto all'elenco man mano che arriva. Nel passaggio successivo, vedrai come assegnare un nome a una superficie e visualizzarla in una posizione specifica all'interno della UI.
Innanzitutto, nella parte superiore di lib/main.dart, prima di void main(), dichiara una costante da utilizzare come ID superficie:
const taskDisplaySurfaceId = 'task_display';
Secondo, in initState(), aggiorna l'istruzione switch nel listener Conversation per assicurarti che qualsiasi superficie con questo ID non venga aggiunta a _items. Per farlo, aggiorna il ramo case ConversationSurfaceAdded added: all'interno di _conversation.events.listen racchiudendo le righe _items.add(...) e _scrollToBottom() all'interno di un'istruzione 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 ...
Successivamente, apri la struttura del layout dell'albero dei widget in _MyHomePageState.build per creare uno spazio per la superficie bloccata immediatamente prima del log della chat. Inserisci AnimatedSize e const Divider() come primi due elementi secondari di Column principale, subito prima del codice 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 ...
Finora, l'agente ha avuto carta bianca per creare e utilizzare le piattaforme come riteneva opportuno. Per fornire istruzioni più specifiche, devi rivedere il prompt di sistema. Aggiungi la seguente sezione ## USER INTERFACE alla fine del prompt archiviato nella costante 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.
''';
È importante fornire all'agente istruzioni chiare su quando e come utilizzare le piattaforme UI. Se indichi all'agente di utilizzare un elemento del catalogo e un ID piattaforma specifici (e di riutilizzare una singola istanza), puoi assicurarti che crei l'interfaccia che vuoi vedere.
C'è ancora del lavoro da fare, ma puoi provare a eseguire di nuovo l'app per vedere l'agente creare la superficie di visualizzazione delle attività nella parte superiore della UI.
7. Crea il tuo widget del catalogo personalizzato
A questo punto, l'elemento del catalogo TaskDisplay non esiste. Nei prossimi passaggi, risolverai il problema creando uno schema di dati, una classe per analizzare lo schema, un widget e l'elemento del catalogo che mette insieme tutto.
Innanzitutto, crea un nuovo file denominato task_display.dart nella directory lib/ del progetto e aggiungi le seguenti importazioni:
import 'package:flutter/material.dart';
import 'package:genui/genui.dart';
import 'package:json_schema_builder/json_schema_builder.dart';
Crea lo schema di dati
Poi, definisci lo schema dei dati che l'agente fornirà quando vuole creare una visualizzazione delle attività. Il processo utilizza alcuni costruttori avanzati del pacchetto json_schema_builder, ma essenzialmente stai solo definendo uno schema JSON utilizzato nei messaggi inviati e ricevuti dall'agente.
Inizia con un S.object di base che fa riferimento al nome del componente:
final taskDisplaySchema = S.object(
properties: {
'component': S.string(enumValues: ['TaskDisplay']),
},
);
Successivamente, aggiungi title, tasks, name, isCompleted e completeAction alle proprietà dello schema.
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.',
),
},
),
),
},
);
Dai un'occhiata alla proprietà completeAction. Viene creato con A2uiSchemas.action, il costruttore di una proprietà dello schema che rappresenta un'azione A2UI. Aggiungendo un'azione allo schema, l'app dice all'agente: "Ehi, quando mi dai un'attività, fornisci anche il nome e i metadati di un'azione che posso usare per comunicarti che l'attività è stata completata". In un secondo momento, l'app richiamerà l'azione quando l'utente tocca una casella di controllo.
Successivamente, aggiungi i campi required allo schema. Queste istruzioni indicano all'agente di compilare determinate proprietà ogni volta. In questo caso, ogni proprietà è obbligatoria.
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'],
);
Crea classi di analisi dei dati
Quando crei istanze di questo componente, l'agente invierà dati corrispondenti allo schema. Aggiungi due classi per analizzare il JSON in entrata in oggetti Dart fortemente tipizzati. Nota come _TaskDisplayData gestisce la struttura principale, delegando l'analisi dell'array interno a _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');
}
}
}
Se hai già utilizzato Flutter, queste classi sono probabilmente simili a quelle che hai creato. Accettano un JsonMap e restituiscono un oggetto con un tipo di dati ben definito contenente i dati analizzati da JSON.
Controlla i campi actionName e actionContext in _TaskData. Vengono estratti dalla proprietà completeAction del file JSON e contengono il nome dell'azione e il relativo contesto dei dati (un riferimento alla posizione dell'azione nel modello di dati di GenUI). Verranno utilizzati in un secondo momento per creare un UserActionEvent.
Il modello di dati è un archivio centralizzato e osservabile per tutto lo stato dell'interfaccia utente dinamica, gestito dalla libreria genui. Quando l'agente crea un componente UI dal catalogo, crea anche un oggetto dati che corrisponde allo schema del componente. Questo oggetto dati viene archiviato nel modello dei dati nel client, in modo che possa essere utilizzato per creare widget e fare riferimento nei messaggi successivi all'agente (come il completeAction che stai per collegare a un widget).
Aggiungi il widget
Ora crea un widget per visualizzare l'elenco. Deve accettare un'istanza della classe _TaskDisplayData e un callback da richiamare al completamento di un'attività.
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);
}
},
),
),
],
);
}
}
Crea l'elemento CatalogItem
Dopo aver creato lo schema, l'analizzatore sintattico e il widget, ora puoi creare un CatalogItem per collegarli tutti.
Nella parte inferiore di task_display.dart, crea taskDisplay come variabile di primo livello, utilizza _TaskDisplayData per analizzare il JSON in entrata e crea un'istanza del 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!
},
);
},
);
Implementa onCompleteTask
Affinché il widget funzioni, deve comunicare all'agente quando un'attività viene completata. Sostituisci il segnaposto vuoto onCompleteTask con il seguente codice per creare e inviare un evento utilizzando completeAction dai dati dell'attività.
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,
),
);
}
Registra elemento del catalogo
Infine, apri main.dart, importa il nuovo file e registralo insieme agli altri articoli del catalogo.
Aggiungi questa importazione all'inizio di lib/main.dart:
import 'task_display.dart';
Sostituisci catalog = BasicCatalogItems.asCatalog(); nella funzione initState() con:
// 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]);
È tutto. Esegui l'hot restart dell'app per visualizzare le modifiche.
8. Sperimenta diversi modi di interagire con l'agente

Ora che hai aggiunto il nuovo widget al catalogo e hai creato uno spazio per lui nell'interfaccia utente dell'app, è il momento di divertirti a lavorare con l'agente. Uno dei principali vantaggi di GenUI è che offre due modi per interagire con i tuoi dati: tramite l'interfaccia utente dell'applicazione, come pulsanti e caselle di controllo, e tramite un agente che comprende il linguaggio naturale e può ragionare sui dati. Prova a sperimentare con entrambi.
- Utilizza il campo di testo per descrivere tre o quattro attività e vederle comparire nell'elenco.
- Utilizza una casella di controllo per contrassegnare un'attività come completata o incompleta.
- Crea un elenco di 5-6 attività, poi chiedi all'agente di rimuovere quelle che richiedono di guidare da qualche parte.
- Chiedi all'agente di creare un elenco ripetitivo di attività come singoli elementi ("Devo comprare un biglietto di auguri per la festa della mamma, del papà e della nonna. Crea attività separate per queste cose.").
- Chiedi all'agente di contrassegnare tutte le attività come completate o non completate oppure di spuntare le prime due o tre.
9. Complimenti
Complimenti! Hai creato un'app di monitoraggio delle attività basata sull'AI utilizzando Generative UI e Flutter.
Cosa hai imparato
- Interagire con i modelli di base di Google utilizzando l'SDK Firebase Flutter
- Rendering di superfici interattive generate da Gemini utilizzando GenUI
- Blocco delle piattaforme nei layout utilizzando ID di rendering statici predeterminati
- Progettazione di schemi personalizzati e cataloghi di widget per loop di interazione efficaci