Variabili template nelle conversazioni
Le variabili template sono segnaposto {{variabile}} inseriti nel system prompt di un agente e compilati con un valore concreto all'inizio di ogni conversazione, sia dalla console Chat sia via API.
Prerequisiti
- Un agente esistente il cui system prompt sarà personalizzato con variabili.
Come funzionano le variabili template
Quando il system prompt di un agente contiene uno o più segnaposto {{nome_variabile}}, la piattaforma li rileva automaticamente e richiede il loro valore prima che la conversazione possa iniziare. I valori compilati sostituiscono i segnaposto nel prompt effettivo inviato al modello, per ogni turno della conversazione.
Un caso d'uso frequente è la variabile {{detected_language}}, valorizzata automaticamente con la lingua rilevata nel primo messaggio dell'utente, usata per far rispondere l'agente nella lingua corretta.
Definirle nel system prompt
Per definire una variabile è sufficiente inserire il segnaposto nel testo del system prompt, ad esempio:
Rispondi sempre in {{detected_language}}. Il cliente si chiama {{nome_cliente}} ed è iscritto al piano {{piano}}.
Non è necessaria una dichiarazione separata: la piattaforma individua automaticamente tutti i segnaposto presenti nel prompt.
Compilarle in console
Quando si avvia una nuova conversazione dalla console Chat con un agente che contiene variabili template, sotto la barra di input compare la sezione Variabili del Prompt con un campo per ciascun segnaposto rilevato. Se un valore obbligatorio viene omesso, l'invio del messaggio viene bloccato con un messaggio di errore.
Passarle via API
Le integrazioni esterne (ad esempio Askme Chat o un'integrazione cliente) possono valorizzare le variabili passandole nel corpo della richiesta di avvio conversazione:
curl -X POST https://api.askme.it/api/v2/chat \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agt_123",
"template_variables": {
"nome_cliente": "Rossi S.p.A.",
"piano": "Business"
},
"message": "Buongiorno, ho una domanda sul mio abbonamento."
}'
Differenza con i placeholder dei Template Prompt
I placeholder {{variabile}} descritti in questa pagina sono compilati all'avvio della conversazione e vivono nel system prompt dell'agente. I placeholder {variabile} usati nei Template Prompt sono invece risolti al momento in cui il template viene inserito nel prompt con la mention "@" (vedere System prompt e istruzioni). I due formati non sono intercambiabili.
Problemi comuni
| Problema | Causa probabile | Soluzione |
|---|---|---|
| L'invio del messaggio viene bloccato | Una variabile obbligatoria non è stata compilata | Compilare tutti i campi richiesti nella sezione Variabili del Prompt |
| Il valore passato via API non viene sostituito | Il nome della variabile nella richiesta non coincide con quello nel system prompt | Verificare che i nomi corrispondano esattamente, incluso il maiuscolo/minuscolo |
| La variabile compare ancora come testo letterale nella risposta | Il segnaposto usa un formato diverso da {{variabile}} (es. singola graffa) | Usare la doppia graffa per le variabili template |