---
title: Interfaccia generativa
description: "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

```bash
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

| Import | API |
| --- | --- |
| `@beeuni/sdk/genui/fence` | Riconoscimento dei blocchi senza dipendenze opzionali |
| `@beeuni/sdk/genui` | Parser, catalogo e conversione Markdown |
| `@beeuni/sdk/genui/react` | Renderer React senza stile predefinito e componenti HTML di base |

## 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.

```tsx
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.

```ts
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.