Novas atualizações do A2UI e do pacote GenUI do Flutter

Conheça as atualizações do A2UI e do pacote GenUI do Flutter para criar interfaces dinâmicas geradas por agentes.

Generative UI, ou GenUI para abreviar, é um padrão de experiência do usuário em que um agente não apenas gera conteúdo, mas também decide como esse conteúdo deve ser exibido e tornado interativo para o usuário. Para desenvolvedores Flutter, implementar GenUI significa usar o A2UI, um protocolo aberto que define uma forma de agentes e clientes (ou “renderizadores”) colaborarem na composição e no estado de uma interface. Para aproveitar isso, a equipe do Flutter criou o genui, um pacote que usa o A2UI para se conectar a um agente, fornecer a ele um catálogo de widgets para usar e, então, apresentar esses widgets ao usuário.

Tanto o pacote genui quanto o protocolo A2UI receberam uma atualização recentemente!

A versão mais recente do genui introduz várias mudanças de arquitetura no framework. Impulsionada pela adoção da v0.9 do protocolo A2UI, esta atualização muda genui de uma filosofia “Structured Output First”, em que as mensagens A2UI eram transmitidas por APIs de saída estruturada, para uma abordagem “Prompt First”, em que os agentes incluem blocos de JSON como texto em suas respostas. Ela também desacopla a arquitetura, oferecendo controle mais direto sobre como a sua aplicação interage com os Large Language Models (LLMs).

Se você está migrando um app da v0.7.0 para a v0.9.0 do pacote genui, este guia cobre os passos necessários, desde a limpeza de dependências até a configuração dos novos loops de chat.

Desacoplamento da arquitetura

Nas versões anteriores, o GenUI dependia de uma série de classes baseadas em ContentGenerator. Essas classes escondiam os detalhes da construção do prompt, das chamadas de rede ao LLM e da análise das respostas.

A versão mais recente do package:genui remove ContentGenerator. Em vez disso, o framework agora é dividido em camadas distintas:

  • Engine (SurfaceController): gerencia o estado e a renderização da sua UI.

  • Transport (A2uiTransportAdapter): transmite mensagens entre o agente e o renderizador.

  • Facade (Conversation): fornece uma API de alto nível para gerenciar os estados do chat.

Esse desacoplamento significa que você tem controle sobre o histórico do chat, a lógica de retentativa e o tratamento de erros. Também significa que você pode configurar a conexão com o seu LLM do jeito que preferir. O framework não “envolve” mais o seu agente com um ContentGenerator, então você fica livre para usar o modelo e o provedor que preferir, ajustar as configurações de geração, adicionar as suas próprias funções e assim por diante, sem precisar passar pela API do framework para isso.

Como o ContentGenerator deixou de existir, os pacotes wrapper específicos de cada provedor não são mais necessários. Se você baixar a versão mais recente do pacote, verá que nomes como genui_dartantic, genui_google_generative_ai e genui_firebase_ai não aparecem mais na árvore.

Esta é a mudança de código mais significativa da migração. Em vez de passar um ContentGenerator para o seu SurfaceController, o seu app passa a ser responsável por configurar uma conexão com um agente e trocar mensagens com ele por meio de um TransportAdapter.

O jeito antigo:

dart
// Create a ContentGenerator that encapsulates interaction with
// the agent.
final generator = FirebaseAiContentGenerator(
  catalog: CoreCatalogItems.asCatalog(),
  systemInstruction: 'You are a helpful assistant.',
);
​
// Create a conversation that links the generator with a GenUiManager
// that manages surfaces, updates, and so on.
final conversation = GenUiConversation(
  genUiManager: GenUiManager(catalog: catalog),
  contentGenerator: generator,
);

O jeito novo:

dart
final catalog = BasicCatalogItems.asCatalog();
​
// Create a SurfaceController to manage the state of generated surfaces.
final surfaceController = SurfaceController(catalogs: [catalog]);
​
// Created a transport adapter that routes messages from the `genui` library
// to the agent, then feeds responses back into the adapter via `addChunk`.
late final adapter = A2uiTransportAdapter(
  onSend: (ChatMessage msg) async {
    // Use a string buffer to prepare tokens to send to the agent.
    final buffer = StringBuffer();
​
    // Iterate over the messages created by the `genui` package, and
    // add them as tokens to the buffer.
    for (final part in msg.parts) {
      if (part.isUiInteractionPart) {
        buffer.write(part.asUiInteractionPart!.interaction);
      } else if (part is genui.TextPart) {
        buffer.write(part.text);
      }
    }
​
    // Send a content generation request to the agent, including the
    // string-ified messages from `genui`
    final response = await myAgentClient.sendRequest(buffer.toString());
​
    // After receiving the agent's response, add it to the `genui` package's
    // input stream using `addChunk`, where it will be parsed for A2UI
    // messages.
    adapter.addChunk(response);
  },
);

Você pode olhar esses dois exemplos e pensar: “Espera, melhorias de API não deveriam significar escrever menos código em vez de mais?” É verdade que antes esse trecho de “fiação” do código para conectar com o agente ficava incluído no pacote genui, escondido em uma classe ContentGenerator, mas a nova abordagem tem algumas vantagens concretas:

  • Sem a exigência de um ContentGenerator, você pode configurar o seu agente do jeito que quiser, mantê-lo em memória onde preferir e gerenciar o seu ciclo de vida. Você também pode usar praticamente qualquer fonte de IA que quiser, sem esperar por uma atualização do pacote com uma nova ContentGenerator.

  • Você não precisa mais “injetar” a sua conexão com o agente na API do genui. Elas são fracamente acopladas, com apenas tokens indo e voltando.

  • Testar fica mais simples. O genui aceita tokens diretamente, e eles podem vir de um agente, de um agente simulado ou de um teste com valores fixos.

  • Se você quiser encapsular a sua conexão em uma classe, ainda pode fazer isso. Na verdade, vários dos exemplos para o genui seguem essa abordagem.

Prompt primeiro

Nas versões anteriores, o pacote genui dependia muito das restrições estritas da API do provedor do LLM (como “JSON Mode” ou definições complexas de function calling) para forçar o modelo a produzir estruturas de UI válidas. O schema era passado ao LLM por fora, por meio de parâmetros específicos da API, e o LLM ficava efetivamente preso a uma estrutura rígida.

Embora isso direcionasse os modelos a criar JSON previsível e bem formatado, schemas profundamente aninhados às vezes confundiam os modelos ou lutavam contra a tendência natural deles de geração de texto. Além disso, depender de saídas estruturadas impunha limites ao tamanho e à complexidade do catálogo. Também tornava a depuração mais difícil, porque as restrições ficavam inteiramente na camada de rede, e não em texto simples que você poderia ler e ajustar facilmente.

A abordagem “prompt primeiro” devolve a fonte da verdade para onde os LLMs se saem melhor: as instruções de sistema. Em vez de depender totalmente de travas estritas da API, o schema da UI e as instruções sobre o A2UI são injetados diretamente no prompt de sistema do LLM como texto simples. O LLM lê as instruções, que detalham exatamente como construir as mensagens para o cliente.

Essa abordagem tem algumas vantagens. Primeiro, os LLMs modernos são muito otimizados para seguir instruções de sistema detalhadas e exemplos. Fornecer o schema no prompt está alinhado com a forma como eles “pensam”. Além disso, como o schema da UI agora é apenas texto simples no seu prompt, você tem a possibilidade de alterá-lo para se adequar à sua aplicação.

Essa mudança significa que a responsabilidade de colocar o prompt certo no contexto do agente agora é da sua aplicação. Felizmente, o pacote genui traz uma nova ferramenta para ajudar você a montar o prompt de sistema certo para a sua aplicação, PromptBuilder. Dado um catálogo e quaisquer instruções adicionais que você queira fornecer, PromptBuilder vai criar um prompt de sistema que inclui as definições de schema e as regras de que o seu LLM precisa para formatar corretamente as mensagens A2UI.

dart
final promptBuilder = PromptBuilder.chat(
  catalog: catalog,
  systemPromptFragments: ['You are a helpful assistant.'],
);

Depois de configurado, o seu app pode obter uma versão String do prompt usando promptBuilder.systemPrompt e então passar esse valor para o LLM.

Ajustes de protocolo e schema

Se o seu código constrói JSON A2UI manualmente ou depende de estruturas de payload específicas, observe estas breaking changes da atualização A2UI v0.9:

  • Criação de surface: beginRendering agora é createSurface.

  • Definições de componentes planas: Em vez de chaves aninhadas (como {"Text": {"text": "Hello"}}), os componentes agora usam um discriminador plano: {"component": "Text", "text": "Hello"}.

  • Data binding: Os bindings foram simplificados. Use { "path": "/path/to/var" } para a resolução de caminhos.

Renomeação de propriedades:

  • distribution => justify

  • alignment => align

  • usageHint => variant

  • text (em TextField) => value

  • userAction => action

Outras coisas foram renomeadas!

Junto com outros pequenos ajustes, o prefixo GenUi foi removido de quase todas as classes principais:

  • GenUiConversation => Conversation

  • GenUiController => SurfaceController

  • GenUiSurface => Surface

  • GenUiHost => SurfaceHost

  • GenUiContext => SurfaceContext

  • GenUiTransport => Transport

  • GenUiFallback => FallbackWidget

Além disso, CoreCatalogItems foi renomeado para BasicCatalogItems para deixar claro que ele serve como uma implementação de referência, e não como um requisito estrito.

Por fim, para alinhar com a terminologia padrão de function calling em LLMs, GenUiFunctionDeclaration e as referências a “tools” foram renomeados para ClientFunction.

O novo pacote genai_primitives

O pacote genui não traz mais os seus próprios tipos de mensagem. Em vez disso, a equipe GenUI criou o novo pacote genai_primitives, com tipos primitivos para funcionalidades comuns necessárias a aplicações GenAI. Esse pacote inclui tipos como ChatMessage, MessagePart e ToolDefinition.

Esses novos tipos são usados em toda a API do pacote genui, e são flexíveis o bastante para se encaixar em outras aplicações ou pacotes de GenAI que você esteja desenvolvendo.

E tem mais!

Além do que foi descrito acima, a versão mais recente do A2UI e do pacote genui traz várias novidades, como:

  • Funções personalizadas, úteis para validar dados no cliente

  • Um schema novo e modular

  • Tratamento de erros aprimorado

Para mais informações sobre isso, confira o post de anúncio da v0.9 e acesse a2ui.org.

Resumo

A atualização mais recente do genui introduz uma arquitetura muito mais idiomática, flexível e robusta. Se você ainda não começou a usar GenUI, não há momento melhor do que agora! Acesse nosso codelab introdutório para ter uma compreensão prática da tecnologia e criar um app funcionando em cerca de 90 minutos.

Mais do Flutter