Variabili del prompt
Le variabili del prompt sono segnaposto nella forma {{variabile}} inseriti nelle istruzioni di un agente e sostituiti con un valore concreto a ogni conversazione, dal canale che la avvia: un'integrazione via API, un widget, l'anteprima della console.
Prerequisiti
- Un agente le cui istruzioni si vogliono personalizzare con valori diversi per ogni conversazione.
Come funzionano
La piattaforma individua automaticamente i segnaposto a doppia graffa presenti nelle istruzioni, senza bisogno di dichiararli. Quando il canale fornisce un valore, questo sostituisce il segnaposto nel testo inviato al modello. Quando il valore non viene fornito, il segnaposto resta nelle istruzioni come testo letterale: l'invio del messaggio non viene bloccato.
Il nome della variabile deve coincidere esattamente con quello indicato dal canale, maiuscole comprese, e va scritto senza spazi tra le graffe.
La variabile {{detected_language}} riporta la lingua rilevata nella conversazione. Viene valorizzata automaticamente nel canale voce (vedere Canale vocale); negli altri canali va fornita come le altre variabili.
Definirle nelle istruzioni
Per definire una variabile è sufficiente scriverla nella sezione Istruzioni, ad esempio:
Rispondi sempre in {{detected_language}}. Il cliente si chiama {{nome_cliente}} e ha attivo il servizio {{servizio}}.
Il collegamento Variabili disponibili, sotto l'editor delle istruzioni, riassume queste regole (vedere Istruzioni dell'agente).
Compilarle nell'anteprima
Nel pannello Anteprima chat della pagina dell'agente, quando le istruzioni contengono variabili compare sopra il campo del messaggio il riquadro richiudibile Variabili e credenziali di prova, con un campo per ciascun segnaposto rilevato. I valori inseriti valgono per i messaggi successivi della conversazione di prova; Nuova conversazione li azzera. L'anteprima usa le istruzioni dell'ultima versione salvata (vedere Anteprima chat).
Nella pagina Chat lo stesso riquadro si chiama Variabili e credenziali di prova per chi può consultare la configurazione degli agenti e Informazioni per l'assistente per gli altri utenti, che vi trovano solo le variabili (vedere Conversare con un agente).
Passarle via API
Le integrazioni valorizzano le variabili nel campo template_vars della richiesta di chat:
curl -X POST "https://ai.askme.it/api/v2/chat" \
-H "X-Api-Key: <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"agent_id": 42,
"message": "Buongiorno, ho una domanda sul mio servizio.",
"template_vars": {
"nome_cliente": "Rossi S.p.A.",
"servizio": "Assistenza tecnica",
"detected_language": "italiano"
}
}'
Un esempio di chiamata già compilato con l'identificativo dell'agente si ottiene dal menu Altre azioni > Esporta (vedere Esportare un agente come codice).
Differenza con i placeholder dei Template Prompt
I segnaposto {{variabile}} descritti in questa pagina sono sostituiti a ogni conversazione. I segnaposto {variabile} a graffa singola dei Template Prompt servono invece all'anteprima del template nella Libreria prompt: quando il template viene inserito nelle istruzioni con «@», vengono copiati così come sono e non sono sostituiti durante la conversazione. Dopo l'inserimento vanno sostituiti a mano, oppure trasformati in variabili a doppia graffa se il valore deve arrivare dal canale.
Problemi comuni
| Problema | Causa probabile | Soluzione |
|---|---|---|
| Il segnaposto compare come testo nelle risposte | Il canale non ha fornito il valore, oppure il nome non coincide | Verificare che il canale invii la variabile con lo stesso nome, maiuscole comprese |
Una variabile scritta con spazi, come {{ nome }}, non viene sostituita | Spazi tra le graffe | Scrivere il segnaposto senza spazi: {{nome}} |
Un segnaposto a graffa singola, come {settore}, non viene sostituito | È il formato dei template, non delle variabili del prompt | Sostituirlo a mano o usare la doppia graffa |
{{detected_language}} resta vuota nelle conversazioni scritte | È valorizzata automaticamente solo nel canale voce | Fornirla dal canale che avvia la conversazione |