Além do texto: Generative UI para sistemas conversacionais

Por que isso importa

O cartão funcionou no caminho feliz; a interface falhou no restante#

Um modelo produz um cartão convincente de resumo da conta durante a demonstração. Em produção, um campo desconhecido quebra a renderização, um resultado parcial deixa uma região vazia, o foco do teclado desaparece após a regeneração e uma ação sem permissão aparece como disponível. A resposta gerada parecia correta; os estados do produto não estavam controlados.

Por isso, interface generativa é primeiro um problema de fronteira entre componentes, não de prompt. O modelo pode escolher entre intenções delimitadas, mas esquemas, componentes testados e permissões da aplicação precisam controlar o que aparece, o que pode ser feito e como cada estado incompleto ou falho se comporta.

Os estados quebrados apontam para uma fronteira de projeto: o modelo pode escolher uma intenção, enquanto componentes testados mantêm o controle da execução.

Contrato de renderização

Separe a escolha do modelo da execução do componente#

As quatro camadas abaixo separam a sugestão do modelo daquilo que a aplicação pode renderizar e executar.

1. 01

   Interpretar

   O modelo identifica o objetivo e escolhe uma ferramenta ou visualização permitida.

2. 02

   Validar

   Um esquema restringe campos, tipos, limites, rótulos e estados vazios.

3. 03

   Renderizar

   Um componente confiável recebe dados validados e cuida da acessibilidade e da interação.

4. 04

   Explicar

   O texto declara o que a visualização mostra, a fonte e a incerteza importante.

Com as responsabilidades separadas, os dados enviados ao componente precisam explicar o que a pessoa está vendo.

Contrato reutilizável

Faça cada visualização explicar seu estado e sua origem#

Um envelope pequeno mantém a intenção de apresentação separada dos dados de negócio. O servidor o valida antes de o cliente escolher um componente; nomes desconhecidos, campos inválidos e ações não permitidas falham de forma segura.

O exemplo é deliberadamente genérico. Em produção, versione o esquema e autorize cada ação no servidor, sem confiar nos valores propostos pelo modelo.

type ViewSpec =
  | { schema_version: "1"; kind: "metric"; label: string; value: number }
  | { schema_version: "1"; kind: "comparison"; rows: Array<{ label: string; value: number }> };

type RenderNode = { component: "MetricCard" | "ComparisonTable"; props: object };

function parseView(input: unknown): ViewSpec | null {
  if (!input || typeof input !== "object") return null;
  const value = input as Record<string, unknown>;
  if (value.schema_version !== "1") return null;
  if (value.kind === "metric" && typeof value.label === "string" && typeof value.value === "number") {
    return value as ViewSpec;
  }
  if (value.kind === "comparison" && Array.isArray(value.rows)) {
    const valid = value.rows.every(row => row && typeof row.label === "string" && typeof row.value === "number");
    return valid ? value as ViewSpec : null;
  }
  return null;
}

const registry = {
  metric: (view: Extract<ViewSpec, { kind: "metric" }>): RenderNode =>
    ({ component: "MetricCard", props: { label: view.label, value: view.value } }),
  comparison: (view: Extract<ViewSpec, { kind: "comparison" }>): RenderNode =>
    ({ component: "ComparisonTable", props: { rows: view.rows } }),
};

export function renderToolResult(input: unknown): RenderNode | { component: "SafeFallback"; props: object } {
  const view = parseView(input);
  if (!view) return { component: "SafeFallback", props: { reason: "invalid_view_contract" } };
  return view.kind === "metric" ? registry.metric(view) : registry.comparison(view);
}

export function authorizeAction(input: { action: string; requires_confirmation: boolean }, confirmed: boolean) {
  if (input.requires_confirmation && !confirmed) return { status: "confirmation_required" };
  return { status: "authorized_for_server_validation", action: input.action };
}

console.log(JSON.stringify([
  renderToolResult({ schema_version: "1", kind: "metric", label: "Conversion", value: 12.4 }),
  renderToolResult({ schema_version: "2", kind: "html", value: "<script>" }),
  authorizeAction({ action: "publish_report", requires_confirmation: true }, false),
], null, 2));

[
  {
    "component": "MetricCard",
    "props": {
      "label": "Conversion",
      "value": 12.4
    }
  },
  {
    "component": "SafeFallback",
    "props": {
      "reason": "invalid_view_contract"
    }
  },
  {
    "status": "confirmation_required"
  }
]

Dados válidos ainda precisam ser apresentados da forma adequada à pergunta da pessoa usuária.

Escolha da visualização

Escolha a representação pela pergunta, não pela novidade#

Use métrica para um valor importante, tabela para consulta precisa, linha para mudança no tempo, barras para comparar categorias e texto quando a evidência não justificar visualização.

Dê ao modelo um catálogo pequeno com descrições e limites. Se nenhum componente servir, volte para texto ou tabela em vez de gerar um gráfico sem suporte.

O caso do resumo da conta mostra como essa escolha funciona quando a conversa vira uma interface de controle.

Padrão sanitizado de produto

A conversa vira uma interface para explorar e controlar a análise#

Em um produto de análise conversacional, a pessoa não pede apenas uma resposta. Ela refina um segmento, compara alternativas, inspeciona evidências e continua a partir do estado atual.

A interface precisa de identificadores estáveis, proveniência e ações reversíveis. Uma continuação como “compare só os dois primeiros” deve transformar dados validados, não reinterpretar uma captura de tela ou um parágrafo.

Depois de definir a visualização útil, estados incompletos e falhos merecem a mesma atenção dada ao sucesso.

Estados operacionais

Carregamento, ausência, resultado parcial, desatualização e erro fazem parte do contrato#

Cada chamada de ferramenta leva tempo e pode falhar sem que as outras falhem. Componentes precisam de estados explícitos e mensagens de status acessíveis; a conversa precisa de uma forma de recuperação que preserve a intenção da pessoa.

Não exiba um gráfico vazio com aparência de certeza quando faltam dados. Mostre a diferença entre ausência de dados, filtro sem resultado, fonte indisponível e falha de ferramenta.

Estado visível não é autorização: toda ação gerada precisa passar pelos controles comuns da aplicação.

Segurança das ações

Um controle gerado ainda precisa de autorização convencional#

Separe a exploração somente de leitura das ações que alteram estado. Um botão proposto pelo modelo não concede permissão: o servidor precisa verificar identidade, escopo, estado atual e operação exata antes de executá-la.

Use identificadores estáveis de ação, idempotência para novas tentativas, confirmação para mudanças destrutivas ou caras e um resultado visível. Quando faltar autorização ou evidência, preserve a análise e desative a ação em vez de adivinhar.

Uma ação segura ainda pode excluir pessoas; por isso, a interface também precisa de um caminho não visual completo.

Acessibilidade

Toda visualização precisa de um caminho não visual#

Verifique estes caminhos em cada componente que o modelo pode selecionar, inclusive nos estados de carregamento, resultado parcial e erro.

• ✓Forneça um resumo textual do principal achado.
• ✓Ofereça tabela ou representação equivalente.
• ✓Não codifique sentido apenas pela cor.
• ✓Anuncie carregamento e resultado programaticamente.
• ✓Mantenha o foco previsível após atualizações.
• ✓Teste reorganização do conteúdo (reflow) e ampliação em telas pequenas.
• ✓Exponha fonte, horário, filtros e incerteza.
• ✓Mantenha ações reversíveis ou confirme as destrutivas.

Juntos, estado, autorização e acessibilidade definem o que o modelo nunca deve gerar livremente.

Conclusão

Gere escolhas, não código de interface sem verificação#

Uma interface generativa confiável não entrega ao modelo o controle do DOM (a estrutura da página no navegador). O modelo seleciona uma intenção limitada; esquemas validam o resultado; componentes testados controlam renderização, acessibilidade, permissões e os estados de carregamento, vazio, parcial, sucesso e erro.

Comece com uma visualização útil e uma lista curta de ações permitidas. Torne cada estado reproduzível sem o modelo, rejeite cargas desconhecidas e registre a intenção selecionada, não o conteúdo sensível da conversa. Se a renderização segura ainda depender de aceitar marcação arbitrária, a fronteira do componente não está pronta.