> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server.

# Come l'AI usa una Mini App

Una Mini App serve a togliere un calcolo dalle mani del modello e darlo a una
regola scritta una volta sola. Questa pagina spiega come avviene lo scambio: cosa
il modello sa della tua Mini App, quando decide di aprirla, e cosa gli torna
indietro.

Vale la pena leggerla prima di collegare una Mini App a un
[agente](/quando-agente): quasi tutti i comportamenti che sembrano strani
(l'interfaccia che si apre mezza vuota, la risposta che si ferma a metà) si
spiegano qui.

## Cosa vede il modello

Il modello non vede l'interfaccia, non vede il codice e non prova la Mini App.
Riceve una scheda di poche righe, presa dalla **versione pubblicata**: una Mini
App mai pubblicata non gli arriva proprio. La scheda contiene:

* Il **nome** della Mini App.
* La sua **descrizione**.
* L'elenco dei **parametri**, con il tipo di ciascuno e, per le scelte, i valori
  ammessi.
* L'elenco degli **output** che si aspetta di ricevere.

Questa scheda ha un limite di lunghezza, e viene tagliata se lo supera. È il
motivo per cui una descrizione lunga e generica lavora contro di te: le parole che
contano rischiano di finire fuori.

| Invece di                | Scrivi                                                                     |
| ------------------------ | -------------------------------------------------------------------------- |
| «Calcolatore»            | «Calcola lo sconto di listino a partire da quantità e categoria prodotto»  |
| «Strumento per le ferie» | «Verifica quanti giorni di ferie restano a una persona nell'anno in corso» |

> **Note**
>
> La descrizione è l'unica cosa su cui il modello decide se la tua Mini App
> c'entra con la richiesta. Scrivila dicendo **cosa calcola e a partire da cosa**,
> non cos'è.

## La sequenza, passo per passo

#### Il modello chiama la Mini App

Mentre risponde, decide che quella richiesta va risolta con la Mini App e la
chiama, compilando i parametri con quello che ha capito.

![Una conversazione: la richiesta sullo sconto per un ordine, la scheda Sconto di listino in attesa con i quattro valori che il modello ha passato, e la risposta che si ferma chiedendo di controllare e confermare](/_fern-img/f19f6067c95ccfdbc909debf6ebdb896507a78205e9b7dc8a4e5be8201ae3946.webp)

#### Il turno si sospende

La risposta si ferma lì. L'AI non prosegue, non inventa un valore e non passa
ad altro: aspetta.

#### L'interfaccia si apre in conversazione

Un clic sulla scheda apre la Mini App in un pannello accanto alla chat, con
i campi già riempiti con i valori che il modello ha proposto.

![Si apre la conversazione, si clicca la scheda in attesa e a destra compare il pannello della Mini App con importo, quantità, categoria e storico già compilati e il risultato calcolato, e il cursore si ferma su Invio](/_fern-files/userbot-035249.docs.buildwithfern.com/fa724a6f3b553ad58cac849ab01d2689ffd6f43f8725f13bc389be7d2f0338fc/docs/assets/animazioni/miniapp-in-chat.gif)

#### Una persona controlla e conferma

Correggi quello che serve e premi **Invio**. Con **Annulla** chiudi senza
eseguire: l'AI viene informata che hai annullato, e prosegue senza quel dato.

![Il pannello della Mini App aperto dalla chat: in alto Annulla e Invio evidenziato, sotto i campi compilati e il risultato del calcolo](/_fern-img/e2e47884a121c30e2fe1d168d138f9d1e8756bee5ffae65bb83e3d1d957f2229.webp)

#### Il turno riprende

Il risultato torna al modello, che continua la risposta da dove si era
fermato: lo mette in una tabella, lo usa in un'email, lo confronta con un
altro caso.

Il punto che conta è il secondo. **Il turno non riprende finché una persona non
conferma.** Non c'è un tempo massimo di attesa e non c'è una risposta di ripiego:
la conversazione resta appesa a quella conferma.

Se premi **Invio** senza aver compilato niente, la Mini App si ferma con
«Compila almeno un campo prima di inviare.»

> **Info**
>
> Fa eccezione la Mini App che dichiara una funzione da eseguire direttamente
> (`toolEntrypoint`). In quel caso l'interfaccia non si apre e il turno non si
> sospende: l'agente esegue la funzione sulla versione pubblicata e continua.
> → [Funzioni server e dati](/miniapp-server)

## Se il modello passa dati incompleti

Un parametro mancante **non fa fallire la chiamata**. La Mini App si apre lo
stesso, con i campi che il modello ha saputo compilare e gli altri vuoti. Tocca a
te finire di riempirli.

È una scelta voluta: meglio un modulo da completare che un errore da leggere. Ma
significa anche che, se ti trovi spesso a compilare a mano gli stessi campi, il
problema è nella descrizione della Mini App o nel nome dei parametri, non nel
modello.

## Cosa vede chi sta guardando

Mentre il turno è sospeso, in conversazione compare una scheda con il nome della
Mini App, l'indicazione che è in attesa e il numero di campi già precompilati.
Cliccandola si apre l'interfaccia, nella sua versione pubblicata.

![La scheda in attesa dentro la conversazione: sotto il nome della Mini App il conteggio dei campi già compilati e i valori che il modello ha proposto, uno accanto all'altro](/_fern-img/3d508b18f38d7c649b6d97486096f242bd41bfdc3761ac24a2d720866815d659.webp)

Se ricarichi la pagina in quel momento la scheda resta lì e la Mini App si riapre
compilata: quello che avevi non va perso, e puoi ancora premere **Invio**. Il
risultato viene registrato nella conversazione, ma **la risposta che si era
interrotta non riparte da sola**: se ti serve che l'AI continui a lavorarci
sopra, chiediglielo nel messaggio successivo. Finché non premi **Invio** o
**Annulla**, la scheda resta dov'è.

A cose fatte, al posto della scheda resta un riepilogo richiudibile marcato
**Inviato**, che aprendolo mostra i valori entrati e quelli usciti. Serve a
ricostruire, tre settimane dopo, con quali numeri era stato prodotto quel
risultato.

## Cosa torna indietro al modello

Non torna un'immagine né un testo discorsivo: torna un dato strutturato con lo
stato della chiamata, i valori che sono entrati e quelli che sono usciti. È per
questo che l'AI può continuare a lavorarci sopra invece di limitarsi a citarlo.

Anche questo pacchetto ha un limite di lunghezza. Se una Mini App restituisce un
elenco enorme, l'AI ne riceve la prima parte. Quando l'output è voluminoso,
conviene farle restituire il risultato (un totale, un esito, un elenco corto) e
non tutti i dati intermedi.

## Collegarla a un agente

Ci sono due modi, e servono a cose diverse.

#### Nelle Azioni dell'agente

Nell'editor dell'agente, riquadro **Azioni**, categoria **Mini App**. Da quel
momento l'agente la può usare sempre, con chiunque, nella sua versione
pubblicata.

#### Con @ in conversazione

Scrivi **@** e il nome della Mini App nel campo di scrittura. Vale **solo per
quel messaggio**: finito il turno, torna non disponibile.

Il criterio: usa le **Azioni** quando la Mini App fa parte del mestiere
dell'agente e deve esserci ogni volta; usa **@** quando serve solo adesso, per
questo caso. → [Collegare azioni](/azioni-agente) e
[Richiamare con @](/menzioni)

> **Warning**
>
> Una Mini App collegata a un agente è eseguibile da **chiunque parli con quell'agente**,
> anche quando il suo accesso generale è **Privato**. La visibilità decide chi la
> trova nell'elenco e chi la può modificare, non chi la può far girare attraverso
> l'agente. Se la formula contiene informazioni riservate, non collegarla a un
> agente condiviso.

## Dove non funziona

Una Mini App si può usare solo in una chat dove **c'è una persona dall'altra
parte**. Il meccanismo si regge sulla sospensione del turno, e un'esecuzione
senza nessuno davanti resterebbe appesa per sempre. Vale anche per le Mini App
con `toolEntrypoint`.

| Contesto                                                        | La Mini App si può usare |
| --------------------------------------------------------------- | ------------------------ |
| Conversazione in chat, con o senza agente                       | Sì                       |
| [Schedulati](/schedulate)                                       | No                       |
| [Automazioni](/automazioni), compreso un agente usato come nodo | No                       |
| Un agente richiamato come sotto-agente da un altro              | No                       |
| La [chat sul sito](/chat-sito) del Customer Service             | No                       |

Se un agente ha una Mini App fra le sue **Azioni** e lo stesso agente viene
eseguito da un'automazione o da un altro agente, in quell'esecuzione la Mini App
non c'è: il modello
non la vede nemmeno, e risolve il calcolo da sé. È esattamente ciò che la Mini App
doveva impedire.

Quando un calcolo deve restare identico anche senza nessuno davanti, la strada non
è la Mini App: è scrivere la regola nelle [istruzioni dell'agente](/istruzioni-agente),
o portare il calcolo dentro un'[automazione](/automazioni), dove ogni passaggio è
definito in anticipo.

#### [Com'è fatta una Mini App](/anatomia-miniapp)

Il contratto, lo schema dei parametri e i limiti di esecuzione.

#### [Pubblicare una Mini App](/pubblicare-miniapp)

Quale versione usa l'agente, e come aggiornarla.