Primeros pasos con el GenUI SDK para Flutter

Esta guía explica cómo dar los primeros pasos con el GenUI SDK para Flutter y su serie de paquetes. Los componentes clave del SDK se describen en la página de componentes principales.

Usa las siguientes instrucciones para agregar genui a tu aplicación Flutter. Los ejemplos de código muestran cómo realizar las instrucciones en una aplicación completamente nueva creada al ejecutar flutter create, pero puedes seguir los mismos pasos para tu aplicación Flutter existente.

El paquete genui puede conectarse a una variedad de proveedores de agentes. Los proveedores disponibles incluyen los siguientes:

Firebase AI Logic

Útil para aplicaciones de producción donde las interacciones con el LLM se realizan por completo en tu cliente de Flutter, sin necesidad de un servidor. Firebase también facilita la entrega de tus funciones de IA de forma segura, ya que Firebase se encarga de la gestión de tu clave de API de Gemini.

GenUI A2UI

Útil para arquitecturas cliente/servidor donde tu agente se está ejecutando en el servidor.

Construir el tuyo propio

También puedes construir tu propio adaptador para conectarte a tu proveedor de LLM preferido. Espera más de nosotros y de la comunidad pronto.

Si compilas tu proyecto Flutter para iOS o macOS, agrega esta clave a tu(s) archivo(s) {ios,macos}/Runner/*.entitlements para habilitar las solicitudes de red salientes:

<dict>
...
<key>com.apple.security.network.client</key>
<true/>
</dict>

A continuación, utiliza las siguientes instrucciones para conectar tu aplicación al proveedor de agentes elegido.

1. Crea un SurfaceController y proporciónale los catálogos de widgets que deseas poner a disposición del agente. Crea un A2uiTransportAdapter para analizar los mensajes y conéctalo.

2. Crea un PromptBuilder y proporciónale una instrucción del sistema y las herramientas (funciones que deseas que el agente pueda invocar). Siempre debes incluir las herramientas proporcionadas por SurfaceController, pero no dudes en incluir otras. Agrega esto al prompt del sistema de tu LLM.

3. Crea una clase Conversation utilizando las instancias de SurfaceController y A2uiTransportAdapter. Tu aplicación interactuará principalmente con este objeto para realizar las tareas.

   Por ejemplo:

   dart

   class _MyHomePageState extends State<MyHomePage> {
     late final SurfaceController _surfaceController;
     late final A2uiTransportAdapter _transportAdapter;
     late final Conversation _conversation;
   ​
     @override
     void initState() {
       super.initState();
   ​
       // Create a SurfaceController with a widget catalog.
       // The BasicCatalogItems contain basic widgets for text, markdown, and images.
       _surfaceController = SurfaceController(catalogs: [BasicCatalogItems.asCatalog()]);
   ​
       // The Conversation wires transport -> controller internally.
       _transportAdapter = A2uiTransportAdapter(onSend: (message) async {
         // Implement sending to LLM and pipe chunks back.
       });
   ​
       final catalog = BasicCatalogItems.asCatalog();
       final promptBuilder = PromptBuilder.chat(
         catalog: catalog,
         systemPromptFragments: [
           '''
           You are an expert in creating funny riddles. Every time I give you a word,
           you should generate UI that displays one new riddle related to that word.
           Each riddle should have both a question and an answer.
           '''
         ],
       );
   ​
       // ... initialize your LLM Client of choice using promptBuilder.systemPromptJoined()
   ​
       // Create the Conversation to orchestrate everything.
       _conversation = Conversation(
         controller: _surfaceController,
         transport: _transportAdapter,
       );
   ​
       // Listen for surface lifecycle events:
       _conversation.events.listen((event) {
         if (event is ConversationSurfaceAdded) {
           _onSurfaceAdded(event);
         } else if (event is ConversationSurfaceRemoved) {
           _onSurfaceDeleted(event);
         }
       });
     }
   ​
     @override
     void dispose() {
       _textController.dispose();
       _conversation.dispose();
       _transportAdapter.dispose();
   ​
       super.dispose();
     }
   }
   

   content_copy

Envía una solicitud al agente utilizando el método sendRequest en la clase Conversation, o transmitiendo directamente a tu cliente de LLM e introduciendo el flujo de resultados en el adaptador mediante el uso de _transportAdapter.addChunk.

Para recibir y mostrar la interfaz de usuario generada:

1. Escucha el flujo de events en Conversation para rastrear la adición y eliminación de superficies de interfaz de usuario a medida que se generan. Estos eventos incluyen un ID de superficie para cada superficie.

2. Construye un widget Surface para cada superficie activa utilizando los ID de superficie recibidos en el paso anterior.

   Por ejemplo:

   dart

   class _MyHomePageState extends State<MyHomePage> {
     // ...
   ​
     final _textController = TextEditingController();
     final _surfaceIds = <String>[];
   ​
     // Send a request containing the user's [text] to the agent.
     void _sendMessage(String text) async {
       if (text.trim().isEmpty) return;
       // await _conversation.sendRequest(ChatMessage.user(TextPart(text)));
     }
   ​
     // Invoked by the events stream listener when a new
     // UI surface is generated. Here, the ID is stored so the
     // build method can create a Surface to display it.
     void _onSurfaceAdded(ConversationSurfaceAdded update) {
       setState(() {
         _surfaceIds.add(update.surfaceId);
       });
     }
   ​
     // Invoked by the events stream listener when a UI surface is removed.
     void _onSurfaceDeleted(ConversationSurfaceRemoved update) {
       setState(() {
         _surfaceIds.remove(update.surfaceId);
       });
     }
   ​
     @override
     Widget build(BuildContext context) {
       return Scaffold(
         appBar: AppBar(
           backgroundColor: Theme.of(context).colorScheme.inversePrimary,
           title: Text(widget.title),
         ),
         body: Column(
           children: [
             Expanded(
               child: ListView.builder(
                 itemCount: _surfaceIds.length,
                 itemBuilder: (context, index) {
                   // For each surface, create a Surface to display it.
                   final id = _surfaceIds[index];
                   return Surface(surfaceContext: _surfaceController.contextFor(id));
                 },
               ),
             ),
             SafeArea(
               child: Padding(
                 padding: const EdgeInsets.symmetric(horizontal: 16.0),
                 child: Row(
                   children: [
                     Expanded(
                       child: TextField(
                         controller: _textController,
                         decoration: const InputDecoration(
                           hintText: 'Enter a message',
                         ),
                       ),
                     ),
                     const SizedBox(width: 16),
                     ElevatedButton(
                       onPressed: () {
                         // Send the user's text to the agent.
                         _sendMessage(_textController.text);
                         _textController.clear();
                       },
                       child: const Text('Send'),
                     ),
                   ],
                 ),
               ),
             ),
           ],
         ),
       );
     }
   }
   

   content_copy

Para tu comodidad, puedes usar el catálogo principal de widgets proporcionado. Sin embargo, la mayoría de las aplicaciones de producción querrán definir un catálogo personalizado de widgets.

Para agregar tus propios widgets, sigue las siguientes instrucciones.

1. Depender del paquete json_schema_builder

   Utiliza dart pub add para agregar json_schema_builder como una dependencia en tu archivo pubspec.yaml:

   $ dart pub add json_schema_builder
   

   content_copy

2. Crear el esquema del nuevo widget

   Cada elemento del catálogo necesita un esquema que defina los datos requeridos para poblarlo. Utilizando el paquete json_schema_builder, define uno para el nuevo widget.

   dart

   import 'package:json_schema_builder/json_schema_builder.dart';
   import 'package:flutter/material.dart';
   import 'package:genui/genui.dart';
   ​
   final _schema = S.object(
     properties: {
       'question': S.string(description: 'The question part of a riddle.'),
       'answer': S.string(description: 'The answer part of a riddle.'),
     },
     required: ['question', 'answer'],
   );
   

   content_copy

3. Crear un CatalogItem

   Cada CatalogItem representa un tipo de widget que el agente tiene permitido generar. Para hacerlo, combina un nombre, un esquema y una función constructora (builder) que produce los widgets que componen la interfaz de usuario generada.

   dart

   final riddleCard = CatalogItem(
     name: 'RiddleCard',
     dataSchema: _schema,
     widgetBuilder:
         (itemContext) {
           final json = itemContext.data as Map<String, Object?>;
           final question = json['question'] as String;
           final answer = json['answer'] as String;
   ​
           final context = itemContext.buildContext;
   ​
           return Container(
             constraints: const BoxConstraints(maxWidth: 400),
             decoration: BoxDecoration(border: Border.all()),
             padding: const EdgeInsets.all(16),
             child: Column(
               crossAxisAlignment: CrossAxisAlignment.start,
               children: [
                 Text(question, style: Theme.of(context).textTheme.headlineMedium),
                 const SizedBox(height: 8.0),
                 Text(answer, style: Theme.of(context).textTheme.headlineSmall),
               ],
             ),
           );
         },
   );
   

   content_copy

4. Agregar el CatalogItem al catálogo

   Incluye los elementos de tu catálogo al instanciar SurfaceController.

   dart

   _surfaceController = SurfaceController(
     catalogs: [BasicCatalogItems.asCatalog().copyWith(newItems: [riddleCard])],
   );
   

   content_copy

5. Actualizar la instrucción del sistema para usar el nuevo widget

   Para asegurarte de que el agente sepa utilizar tu nuevo widget, indícale a la instrucción del sistema cómo y cuándo hacerlo. Proporciona el nombre del CatalogItem al hacerlo.

   dart

   final promptBuilder = PromptBuilder.chat(
     catalog: catalog,
     systemPromptFragments: [
       '''
       You are an expert in creating funny riddles. Every time I give you a word,
       generate a RiddleCard that displays one new riddle related to that word.
       Each riddle should have both a question and an answer.
       '''
     ],
   );
   ​
   // Pass promptBuilder.systemPromptJoined() to your LLM Config
   

   content_copy

Un concepto central en genui es el DataModel, un almacén centralizado y observable para todo el estado dinámico de la interfaz de usuario. En lugar de que cada widget gestione su propio estado, su estado se almacena en el DataModel.

Los widgets están vinculados a los datos en este modelo. Cuando cambian los datos en el modelo, solo se reconstruyen los widgets que dependen de ese fragmento de datos específico. Esto se logra a través de un objeto DataContext pasado a la función constructora de cada widget.

Para vincular la propiedad de un widget al modelo de datos, especifica un objeto JSON especial en los datos enviados desde la IA. Este objeto puede contener primitivas JSON estándar (para valores estáticos) o un objeto con una propiedad path (para vincularlo a un valor en el modelo de datos).

Por ejemplo, para mostrar el nombre de un usuario en un widget Text, la IA generaría:

{
  "id": "welcome-text",
  "component": "Text",
  "text": "Welcome to GenUI",
  "variant": "h1"
}

{
  "id": "image",
  "component": "Image",
  "url": "https://example.com/image.png",
  "variant": "mediumFeature"
}

Los widgets de entrada, como TextField, actualizan el DataModel directamente. Cuando el usuario escribe en un campo de texto que está vinculado a /user/name, el DataModel se actualiza, y cualquier otro widget vinculado a esa misma ruta se reconstruirá automáticamente para mostrar el nuevo valor.

Este flujo de datos reactivo simplifica la gestión del estado y crea un bucle de interacción potente y de gran ancho de banda entre el usuario, la interfaz de usuario y la IA.

Consulta los ejemplos incluidos en el repositorio de genui. La aplicación travel app muestra cómo definir tu propio catálogo de widgets que el agente puede usar para generar una interfaz de usuario específica de tu dominio.

Si algo no está claro o falta, por favor crea un problema.

El paquete genui le da al LLM un conjunto de herramientas que puede usar para generar interfaces de usuario. Para lograr que el LLM use estas herramientas, las instrucciones del sistema proporcionadas a través de PromptBuilder deben indicarle explícitamente que lo haga.

Es por esto que el ejemplo anterior incluye una instrucción del sistema para el agente con la línea "Cada vez que te dé una palabra, debes generar una interfaz de usuario que...":

final promptBuilder = PromptBuilder.chat(
  catalog: catalog,
  systemPromptFragments: [
    '''
    You are an expert in creating funny riddles.
    Every time I give you a word, you should generate UI that
    displays one new riddle related to that word.
    Each riddle should have both a question and an answer.
    '''
  ],
);

Para observar la comunicación entre tu aplicación y el agente, habilita el registro de log en tu método main.

import 'package:logging/logging.dart';
import 'package:genui/genui.dart';
​
final logger = configureLogging(level: Level.ALL);
​
void main() async {
  logger.onRecord.listen((record) {
    debugPrint('${record.loggerName}: ${record.message}');
  });
​
  // Additional initialization of bindings and Firebase.
}

Firebase tiene un requisito de versión mínima para las plataformas de Apple, el cual podría ser más alto que el valor predeterminado de Flutter. Revisa tu Podfile (para iOS) y CMakeLists.txt (para macOS) para asegurarte de que estás apuntando a una versión que cumpla o supere los requisitos de Firebase.