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.

Aprenda a usar funções do lado do cliente

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:

  1. 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.
  2. 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).
  3. 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.

dart
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:

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:

  1. name: O identificador único (calculateCost) que o agente de IA usa ao gerar chamadas de função dentro de payloads A2UI.
  2. 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.
  3. returnType: Especifica o tipo de dado retornado pela função (neste caso, uma string).
  4. argumentSchema: Construído usando json_schema_builder, este schema informa ao LLM exatamente quais parâmetros são obrigatórios (ingredient_id e quantity).
  5. executeSync: O método Dart principal executado no dispositivo do usuário quando a UI é renderizada. Ele faz o parse dos argumentos recebidos, chama meu CostService local 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:

dart
// 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):

json
{
  "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?

Bom desenvolvimento!

Mais do Flutter