Interfaccia generativa

Mostra le risposte strutturate dell'agente nel tuo prodotto.

Con Generative UI attiva nel progetto, le risposte possono contenere blocchi openui accanto al Markdown: schede, confronti, checklist, grafici, mappe e schede a linguette. Testo e codice restano in Markdown.

Installazione

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

Installa le dipendenze opzionali prima di importare il parser o il renderer React. L’ingresso principale dell’SDK e gli hook React non le caricano.

Punti di ingresso

Visualizzare un blocco

Riconosci il blocco nel renderer Markdown con genuiVersionFromClassName(className). null indica un normale blocco di codice. Carica il renderer solo quando compare un blocco 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}
    />
  );
}

Passa i tuoi componenti con components, oppure inizia con defaultGenuiComponents. Mantieni stabile renderMarkdown. Imposta streaming su false appena il blocco si chiude, anche se la risposta continua.

renderPending può riservare spazio per elementi grandi ancora incompleti. enabled={false} mostra il Markdown. onSettled riporta esito e durata una volta per blocco, senza il contenuto.

Testo e compatibilità

Usa genuiToMarkdown(text) nelle interfacce di solo testo. I grafici diventano tabelle e le mappe elenchi di luoghi; linguette e pannelli si espandono. Durante lo streaming passa { streaming: true } per evitare avvisi prematuri di troncamento.

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

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

I blocchi non validi o non supportati mostrano un contenuto alternativo senza eseguirlo. Aggiorna l’SDK per i nuovi tipi. Le spunte delle checklist restano nel componente: Beeuni non le salva né le invia.

Sicurezza

I blocchi contengono dati, non codice eseguibile. Link e immagini richiedono URL assoluti http o https. L’interfaccia generata non può eseguire strumenti né modificare lo stato dell’applicazione.