Interface generativa

Mostre respostas estruturadas do agente no seu produto.

Com Generative UI ativada no projeto, as respostas podem incluir blocos openui junto ao Markdown: cartões, comparações, checklists, gráficos, mapas e abas. Texto e código continuam em Markdown.

Instalação

npm install @beeuni/sdk zod @openuidev/lang-core@0.3.1
# React:
npm install react

Instale as dependências opcionais antes de importar o parser ou renderer React. A entrada principal do SDK e os hooks React não as carregam.

Pontos de entrada

Renderizar um bloco

Detecte o bloco no renderer Markdown com genuiVersionFromClassName(className). null indica um bloco de código comum. Carregue o renderer sob demanda quando surgir um bloco generativo.

import type { ReactNode } from 'react';
import { GenuiBlock, defaultGenuiComponents } from '@beeuni/sdk/genui/react';
import { genuiVersionFromClassName } from '@beeuni/sdk/genui/fence';

type Props = {
  code: string;
  className?: string;
  streaming: boolean;
  renderMarkdown: (markdown: string) => ReactNode;
};

function StructuredReply({ code, className, streaming, renderMarkdown }: Props) {
  const version = genuiVersionFromClassName(className);
  if (version === null) return <pre><code>{code}</code></pre>;
  return (
    <GenuiBlock
      code={code}
      version={version}
      streaming={streaming}
      components={defaultGenuiComponents}
      renderMarkdown={renderMarkdown}
    />
  );
}

Passe seus componentes por components ou comece com defaultGenuiComponents. Mantenha renderMarkdown estável. Defina streaming como false assim que este bloco fechar, mesmo que a resposta continue.

renderPending pode reservar espaço para elementos grandes ainda incompletos. enabled={false} mostra Markdown. onSettled informa resultado e tempo uma vez por bloco, sem o conteúdo.

Texto e compatibilidade

Use genuiToMarkdown(text) em interfaces de texto. Gráficos viram tabelas e mapas viram listas de lugares; abas e painéis se expandem. Durante o streaming, passe { streaming: true } para evitar avisos prematuros de corte.

import { genuiToMarkdown } from '@beeuni/sdk/genui';

const markdown = genuiToMarkdown(reply, { streaming: true });

Blocos inválidos ou não suportados mostram uma alternativa sem executar conteúdo. Atualize o SDK para novos tipos. As seleções das checklists ficam no componente; o Beeuni não as salva nem envia.

Segurança

Os blocos contêm dados, não código executável. Links e imagens exigem URLs absolutas http ou https. A interface gerada não executa ferramentas nem altera o estado da aplicação.