Integrate GenUI with Firebase AI Logic

Goal

To successfully integrate the genui package into a Flutter app and set up a basic conversational agent using Firebase AI Logic. This skill assumes Firebase AI Logic is already set up and working in the project.

Instructions

When tasked with integrating genui and starting a simple conversation, follow these steps:

1. Verify Firebase Setup: Ensure firebase_core and firebase_ai are available in pubspec.yaml. Verify that Firebase.initializeApp is called in the main() function:

   WidgetsFlutterBinding.ensureInitialized();
   await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
   

2. Add GenUI Package: Add genui to the pubspec.yaml dependencies.

3. Import Required Libraries: Import genui and hide TextPart so it doesn't conflict with other packages, then import it again with an alias:

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

4. Configure Basic Logging: At the beginning of the main() function, configure GenUI logging:

   configureLogging(
     logCallback: (level, msg) => debugPrint('GenUI $level: $msg'),
   );
   

5. Create Model and Chat Session: Initialize the generative model and start a chat session.

   final model = FirebaseAI.googleAI().generativeModel(
     model: 'gemini-3-flash-preview',
   );
   final _chatSession = model.startChat();
   

6. Identify Target StatefulWidget: STOP AND ASK THE USER IF UNCLEAR: This integration requires a StatefulWidget to hold the references to GenUI controllers (SurfaceController, A2uiTransportAdapter, and Conversation). Identify which StatefulWidget to use in the application. If you are unsure which widget should hold this state, ask the user before proceeding.

7. Wire up GenUI Controllers inside State: Inside your identified State class, instantiate SurfaceController, A2uiTransportAdapter, and Conversation:

   final catalog = BasicCatalogItems.asCatalog(); // Optionally inject custom CatalogItems
   final _controller = SurfaceController(catalogs: [catalog]);
   final _transport = A2uiTransportAdapter(onSend: _sendAndReceive);
   final _conversation = Conversation(
     controller: _controller,
     transport: _transport,
   );
   

8. Implement the _sendAndReceive Method: Create a method to take messages from the transport adapter, send them to Firebase, and feed the AI's response back to the transport.

   Future<void> _sendAndReceive(ChatMessage msg) async {
     final buffer = StringBuffer();
   
     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();
     final response = await _chatSession.sendMessage(Content.text(text));
   
     if (response.text?.isNotEmpty ?? false) {
       _transport.addChunk(response.text!);
     }
   }
   

9. Listen to Conversation Events: Create stubbed-out methods in your State class for each event type, including DartDoc comments explaining their required behavior. Depending on the interface design, new surfaces and text coming from the agent will be handled in different ways. A conversational interface might add everything to a list that's display in a ListView, for example, while an interface featuring UI components in specific locations (such as headers, footers, etc.) might rely on specific surface IDs given to the agent in the system instruction to know which surfaces to display in which locations.

   /// Updates state to include the new [surfaceId] so a new `Surface` widget can be built.
   void _onSurfaceAdded(String surfaceId) {
     // TODO: Implement state update to add surfaceId
   }
   
   /// Updates state to remove the [surfaceId] so its `Surface` widget is no longer built.
   void _onSurfaceRemoved(String surfaceId) {
     // TODO: Implement state update to remove surfaceId
   }
   
   /// Handles displaying raw text content received from the AI to the user.
   void _onContentReceived(String text) {
     // TODO: Implement displaying the received text
   }
   
   /// Handles errors that occur during the conversation appropriately.
   void _onError(Object error) {
     // TODO: Implement error handling
   }
   

   Subscribe to _conversation.events to track when UI surfaces or chat messages arrive, dispatching them to the appropriate stubbed out methods:

   _conversation.events.listen((event) {
     switch (event) {
       case ConversationSurfaceAdded added:
         _onSurfaceAdded(added.surfaceId);
       case ConversationSurfaceRemoved removed:
         _onSurfaceRemoved(removed.surfaceId);
       case ConversationContentReceived content:
         _onContentReceived(content.text);
       case ConversationError error:
         _onError(error.error);
       default:
     }
   });
   

10. Initialize System Prompt: Use PromptBuilder to give the AI basic instructions, then send it as a system message.

    final promptBuilder = PromptBuilder.chat(
      catalog: catalog,
      instructions: 'You are a helpful assistant. Respond to messages in a chatty way.',
    );
    _conversation.sendRequest(ChatMessage.system(promptBuilder.systemPrompt));
    

11. Display Surfaces: In your Flutter build() method, use the Surface widget wherever you need to render GenUI widgets using the surfaceIds you collected in step 9.

    Surface(surfaceContext: _controller.contextFor(surfaceId));
    

12. Ask User for Input Preferences: STOP AND ASK THE USER: Ask the user for clarification on what UI elements should be used for user input. Explain that a TextField and ElevatedButton are good defaults, but you should not assume they want those exact widgets unless they clarify.

Constraints

• Do not make assumptions about user input UI elements; see step 12.
• Make sure to properly clean up GenUI controllers (_transport.dispose(), _controller.dispose()) inside the widget's dispose() method.