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: 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.
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.
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.
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.»
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
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.
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.
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 e Richiamare con @
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.
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, o portare il calcolo dentro un’automazione, dove ogni passaggio è definito in anticipo.