Voglio condividere la mia esperienza dell’utilizzo delle funzioni di App.AI su applicazioni web realizzate con Instant Developer Studio, che possono valere anche per Cloud visto che l’approccio è lo stesso.
Il contesto
Una cosa fondamentale sono le descrizioni degli elementi del progetto:
- applicazione
- tabelle del database
- campi delle tabelle
- classi della DO e dei custom tool
Tutte le descrizioni di questi elementi devono essere coerenti al compiti che svolge ogni singolo componente e dettagliate, non temete di esagerare.
Anche il formato di una descrizione può migliorare la comprensione e l’utilizzo da parte dell’agente AI.
Per esempio un prompt come questo:
"Analizza il file pdf che ti ho caricato e cerca i seguenti dati: data fattura, numero fattura, ragione sociale fornitore, importo totale, partita iva del fornitore"
è meglio scriverlo in questo modo:
Analizza il file pdf che ti ho passato, che rappresenta una fattura fornitore.
Estrai da esso i seguenti campi:
- data fattura,
- numero fattura,
- ragione sociale fornitore,
- importo totale,
- partita iva del fornitore
Quindi essere più dettagliati che si può in modo da non causare equivoci e specificare bene cosa si vuole ottenere, dicendo all’agente che è una fattura fornitore e passando i campi in una lista gli facilita il lavoro e potrebbe anche consumare meno token.
Esempi di descrizioni
La descrizione di un’applicazione che carica fatture da file pdf potrebbe essere:
Applicazione per il carico dei dati di fatture da fornitore tramite l'analisi di file pdf che rappresentano la fattura.
Tabella Categories:
Tabella delle categorie dei prodotti venduti.
Campo ProductName:
Nome che identifica il prodotto.
Classe CustomToolGestioneFatture:
Custom tool per la gestione delle Fatture da fornitore che contiene le funzioni che parmetto l'inserimento dei dati nella tabelle del database relative ad esse.
Funzione inseriscDatiFatturaFornitore:
Questa funzione inserisce un record nella tabella FattureFornitore a partire dai dati estratti da un file pdf che indentifica la fattura.
La funzione ritorna "Ok" se tutto ok, oppure la lista dei messaggio di errore preceduta dalla parola Error.
Uso delle costanti
Su Studio come scriviamo una stringa con gli a capo?
Come ben sapete il VCE (Visual Code Editor) non è molto amichevole con le costanti molto lunghe e mettere gli a capo vuol dire aggiungere dei \n nella costante e certamente non ne migliora la visibilità.
Il nostro prompt formattato nel VCE diventa questo:
Studio però ci da un aiuto per scriverla meglio e possiamo utilizzare il bottone con la scritta Tx presente nell’area delle proprietà che ci permette di editare il valore in una text area.
Cliccando questo bottone possiamo editare il testo in maniera più agevole.
Bottoni custom nella chat AI
Un testo complesso per un prompt non lo faremo certamente scrivere da un’utente della nostra app ma potremmo predisporre un bottone nella chat che l’utente può utilizzare dopo aver caricato il pdf con queste righe di codice:
aic.allowAttachments = true
aic.addConversationStarter(prompFatturaFornitore, "Elabora fattura fornitore da pdf caricato", [icon])
Dove aic è l’istanza della chat dell’agente AI e nella variabile prompFatturaFornitore abbiamo impostato il testo del prompt. La prime riga abilita il caricamento di allegati nella chat.
Evento AIBuildSystemPrompt
L’evento AIBuildSystemPrompt serve a personalizzare il prompt che l’utente invia all’agente dalla chat.
Possiamo utilizzare il parametro CustomInstructions per aggiungere nostre istruzioni per l’agente come ad esempio:
CustomInstructions = "Utilizza sempre i custom tool presenti e disattiva il il tool sql. \nAttenzione al formato delle date da passare al custom tool che è sempre dd/mm/yyyy. \nSe un custom tool ritorna più risultati e te ne spetti uno solo chiedi all'utente quale risultato utilizzare per proseguire il lavoro."
In questo caso stiamo forzando l’utilizzo dei custom tool e dicendo di non provare nemmeno ad utilizzare il tool sql, specifichiamo il formato delle date e diamo istruzioni nel caso di risultati multipli per i custom tool che dovrebbero prevedere un solo risultato.
Implementando questo evento nel debug di trace dell’applicazione vediamo come sono impostati i parametri di default del prompt dal:
Trattamento delle date
Utilizzando una funzione di un custom tool per inserire dei record in una tabella del database occorre che siano gestiti i parametri che l’agente AI passerà alla funzione.
Se definiamo i campi data come dei date e specificando il formato in genere l’agente fa quel che deve ma alle volte il campo data viene valorizzato in modo errato e poi facendo operazioni sulla data (tipo aggiungere un giorno) si possono ottenere risultati non previsti.
La cosa migliore è gestire i campi data come stringhe specificando come la data deve essere passata nel commento del parametro.
Per esempio:
public string CustomToolGestioneTurni.inserisciTurno(
int idDipendente // Id del dipendente
string dataInizio // Data inizio in formato dd/mm/yyyy
string dataFine // Data fine in formato dd/mm/yyyy
)
Poi nel codice sapendo il formato ricevuto lo trattiamo in questo modo:
date dInizio = toDate(toInteger(mid(dataInizio, 7, 4)), toInteger(mid(dataInizio, 4, 2)), toInteger(mid(dataInizio, 1, 2)))
date dFine = toDate(toInteger(mid(dataFine, 7, 4)), toInteger(mid(dataFine, 4, 2)), toInteger(mid(dataFine, 1, 2)))
In questo modo non ho più avuto problemi.
Caricamento di pdf nella KB
Se si vogliono caricare documenti nella knowledge base occorre indicare anche una chiave di OpenAI come provider che per ora è l’unico che mette a disposizione l’API per creare gli embedding.
Quindi, al momento del caricamento di un documento nella knowledge base, il sistema verifica se è stata fornita una chiave OpenAI. Se c’è prosegue, se no non può proseguire e scrive un messaggio nel debug.
Quindi potrei anche caricare più key di vari provider e poi indicare quale utilizzare come default magari in base alla login.