Cálculos rápidos e confiáveis com as Funções do Cliente do A2UI
Saiba como as funções do cliente permitem que um agente delegue operações locais diretamente para código Dart executado no dispositivo do usuário.
A UI generativa (GenUI) está transformando a forma como eu abordo o desenvolvimento de UI
no Flutter. Em vez de codificar telas fixas
para cada cenário, a GenUI permite que um agente de IA gere e ajuste dinamicamente
componentes de interface em tempo de execução. Usando mensagens JSON do Agent-to-User Interface (A2UI) e o
genui pacote, um app Flutter
pode renderizar cards e superfícies dinâmicos guiados por IA em tempo real.
No entanto, conforme comecei a criar apps agênticos do mundo real, percebi que estava procurando formas de reduzir a latência e diminuir o número de oportunidades que meus modelos têm de cometer erros. Ao criar com Large Language Models (LLMs), é tentador depender do modelo para tudo. Mas pedir a um LLM que execute tarefas para as quais ele não foi necessariamente projetado (como aritmética) pode introduzir latência e criar mais oportunidades de erro.
É aí que entram as funções do lado do cliente do A2UI.
Neste post, vou explicar como as funções do lado do cliente permitem que um agente delegue operações locais diretamente para código Dart executado no dispositivo do usuário, reduzindo a necessidade de idas e voltas e entregando resultados mais previsíveis nos seus apps Flutter GenUI.
O que as funções do lado do cliente resolvem
Enviar prompts brutos de ida e volta para um LLM apenas para fazer contas é ineficiente, adicionando latência de rede e consumindo tokens extras. Em vez disso, as funções do lado do cliente permitem que o agente calcule valores como custos de ingredientes, totais de impostos ou conversões de unidades localmente no dispositivo.
As funções do lado do cliente resolvem isso criando uma divisão clara de responsabilidades:
- O cliente Flutter declara as funções disponíveis do lado do cliente no catálogo do GenUI, informando ao agente quais operações locais podem ser invocadas, quais parâmetros esperam e em qual formato retornam.
- O agente de LLM decide quando e onde um componente deve ser exibido e emite uma expressão A2UI que chama a função do cliente com os argumentos necessários (como um ID de item e uma quantidade).
- O cliente Flutter avalia a expressão localmente e executa o cálculo de forma síncrona em código Dart, renderizando um resultado limpo e formatado na tela imediatamente.
Ao transferir os cálculos para o dispositivo do cliente, seu app evita sobrecarga de rede desnecessária, obtém formatação consistente e reduz o uso total de tokens.
sequenceDiagram
participant LLM as Gemini Agent
participant Client as Flutter App (genui)
participant Function as CalculateCost (Dart)
LLM->>Client: A2UI Payload with calculateCost(black_beans, 3)
Client->>Function: executeSync(args)
Function->>Client: "$2.97"
Client->>Client: Render Text widget ($2.97)
Vamos ver como implementei esse padrão em um app de exemplo chamado Commis, um assistente inteligente criado para cozinhas comerciais e equipes de buffet.
Anatomia da classe CalculateCostFunction
Ao se preparar para um próximo evento de buffet, um chef pode fazer
perguntas sobre os ingredientes usados no cardápio. Para calcular e
exibir os custos dos ingredientes de forma confiável, sem esperar por idas e voltas ao servidor, criei uma
função do lado do cliente chamada CalculateCostFunction.
No pacote genui, funções síncronas do lado do cliente estendem
SynchronousClientFunction. Aqui está a implementação completa
de client_functions.dart:
/// A client-side function that calculates the cost for an ingredient
/// directly on the device using local Dart logic.
class CalculateCostFunction extends SynchronousClientFunction {
const CalculateCostFunction();
// 1. The identifier referenced by the LLM in A2UI payloads.
@override
String get name => 'calculateCost';
// 2. Clear description provided to the LLM so it knows when
// and why to use the function.
@override
String get description =>
'Calculates the cost for a certain quantity of an ingredient. '
'Returns a formatted dollar string (for example, \$4.50).';
// 3. The expected return type for the binding.
@override
ClientFunctionReturnType get returnType => ClientFunctionReturnType.string;
// 4. JSON Schema defining required input arguments.
@override
Schema get argumentSchema => S.object(
properties: {
'ingredient_id': S.string(description: 'The ID of the ingredient.'),
'quantity': S.number(description: 'The quantity of the ingredient.'),
},
required: ['ingredient_id', 'quantity'],
);
// 5. Synchronous Dart execution logic on the client
@override
Object? executeSync(JsonMap args, ExecutionContext context) {
final ingredientId = args['ingredient_id'].toString();
final quantity = num.tryParse(args['quantity'].toString())?.toDouble();
if (quantity == null || quantity < 1) {
return '\$0.00';
}
// Call the local cost service to fetch price and format as currency
final cost = CostService().fetchPrice(ingredientId, quantity);
return '\$${cost.toStringAsFixed(2)}';
}
}
Vamos analisar as partes principais desta classe:
-
name: O identificador único (calculateCost) que o agente de IA usa ao gerar chamadas de função dentro de payloads A2UI. -
description: Uma explicação concisa enviada ao LLM para que ele saiba quando e por que invocar esta função e qual formato de saída esperar. -
returnType: Especifica o tipo de dado retornado pela função (neste caso, uma string). -
argumentSchema: Construído usandojson_schema_builder, este schema informa ao LLM exatamente quais parâmetros são obrigatórios (ingredient_idequantity). -
executeSync: O método Dart principal executado no dispositivo do usuário quando a UI é renderizada. Ele faz o parse dos argumentos recebidos, chama meuCostServicelocal e retorna a string formatada em dólar.
Se você percebeu que esse padrão se parece muito com o usado para entradas de catálogo de componentes de UI, você acertou em cheio! Ambos fornecem metadados para o agente usar no raciocínio, pareados com lógica Dart que faz algo útil: ou cria widgets ou, neste caso, calcula um valor.
Registro no catálogo e integração com o prompt de sistema
Para tornar o agente ciente de calculateCost, eu o registro no
Catalog do GenUI do meu app.
Ao instanciar Catalog, passo CalculateCostFunction() para a
lista functions junto com meus componentes de UI:
// lib/ui/catalog/catalog.dart
final commisCatalog = Catalog(
[
cateringJobItem,
recipeLineCatalogItem,
ingredientLineCatalogItem,
navigationCardCatalogItem,
simpleCardCatalogItem,
],
functions: [
CalculateCostFunction(), // Here it is!
],
catalogId: 'commis_catalog',
);
Quando a sessão de conversa é inicializada,
o PromptBuilder de genui inspeciona o catálogo e extrai automaticamente
todas as declarações de funções do cliente, incorporando seus nomes,
descrições e schemas ao prompt de sistema enviado ao Gemini.
Com isso pronto, quando um chef pergunta sobre o preço de uma receita, o Gemini não tenta adivinhar nem calcular o total em dólar. Em vez disso, ele emite uma mensagem A2UI contendo uma chamada para calculateCost (neste caso, para o preço de três latas de feijão):
{
"id": "cost_val",
"component": "Text",
"text": {
"call": "calculateCost",
"args": {
"ingredient_id": "black_beans",
"quantity": 3
},
"returnType": "string"
},
"variant": "h2"
}
Repare como o valor da propriedade call na mensagem A2UI corresponde
ao nome da função (calculateCost) registrado no catálogo. Quando o
SurfaceController recebe essa mensagem, ele avalia calculateCost
localmente no dispositivo usando executeSync e renderiza a
string em dólar precisa (como $2.97) na tela imediatamente.
Iteração rápida no desenvolvimento com Flutter Hot Reload
Como as funções do lado do cliente não ficam presas atrás de um microsserviço de backend ou de um deploy de cloud function, trabalhar com elas ainda parece o bom e velho Dart.
Se eu quiser atualizar a formatação de moeda (por exemplo, adicionando lógica de desconto
por volume ou trocando $4.50 por USD 4.50), basta editar
executeSync em Dart, salvar o arquivo e ver o hot reload atualizar
meu app com o novo resultado.
Resumo e próximos passos
Pronto para experimentar o GenUI e as funções do lado do cliente nos seus próprios apps?
- Confira o Intro to GenUI Codelab oficial para aprender o básico de Generative UI.
-
Explore o pacote
genuino pub.dev para detalhes da API e definições de catálogo. - Navegue pelo flutter/demos repositório no GitHub para inspecionar o código-fonte completo do Commis e de outros exemplos de GenUI em Dart.
Bom desenvolvimento!