Azioni e parametri

In questa pagina vengono descritte le impostazioni di azioni e parametri per gli intent e il modo in cui vengono utilizzati quando gli intent vengono abbinati in fase di runtime.

Dove trovare questi dati

Durante la creazione di un agente, è più comune utilizzare Dialogflow ES Console (consulta la documentazione, apri la console). Le istruzioni riportate di seguito sono incentrate sull'utilizzo della console. Per accedere ai dati di azioni e parametri:

  1. Vai alla console Dialogflow ES.
  2. Seleziona un agente.
  3. Seleziona Intent nel menu della barra laterale a sinistra.
  4. Seleziona un intent.
  5. Scorri verso il basso fino alla sezione Azione e parametri.

Screenshot dei campi Azione e Parametri

Se stai creando un agente utilizzando l'API anziché la console, consulta la documentazione di riferimento per gli intent. I nomi dei campi API sono simili a quelli dei campi della console. Le istruzioni riportate di seguito evidenziano eventuali differenze importanti tra la console e l'API.

Azioni

Il campo action è un semplice campo di convenienza che assiste nell'esecuzione della logica nel servizio.

Quando crei un agente, puoi impostare questo campo su qualsiasi testo che ritieni utile.

Quando viene trovata una corrispondenza di un intent in fase di runtime, Dialogflow fornisce il valore dell'azione alla richiesta webhook di fulfillment o alla risposta di interazione API. Può essere usato per attivare logica specifica nel servizio.

Parametri

Quando viene trovata una corrispondenza di un intent in fase di runtime, Dialogflow fornisce i valori estratti dall'espressione dell'utente finale come parametri. Ogni parametro ha un tipo, chiamato tipo di entità, che determina esattamente il modo in cui vengono estratti i dati. A differenza dell'input non elaborato dell'utente finale, i parametri sono dati strutturati che possono essere facilmente utilizzati per eseguire una logica o generare risposte.

Quando crei un agente, puoi controllare il modo in cui vengono estratti i dati annotando le parti delle frasi di addestramento e configurando i parametri associati.

Il seguente elenco mostra i campi di una configurazione di parametri. Esempi sono mostrati per la frase di addestramento "prenota una stanza per martedì", con l'annotazione "martedì".

  • Obbligatorio: seleziona questa casella se il parametro è obbligatorio per completare l'intent. Consulta la sezione Riempimento degli slot con i parametri richiesti di seguito.
  • Nome parametro: un nome che identifica il parametro. Esempio: date.
  • Entità: il tipo di entità associato al parametro. Esempio: @sys.date.
  • Valore: nella maggior parte dei casi, è impostato su un riferimento a un parametro come $parameter-name, che viene utilizzato come segnaposto per il valore estratto al momento dell'esecuzione. Tuttavia, questo campo può essere utilizzato anche per selezionare valori alternativi. Consulta la sezione Valori dei parametri e riferimenti ai parametri di seguito. Esempio: $date.
  • Is List: seleziona questa casella se i valori devono essere restituiti sotto forma di elenco. Consulta la sezione Parametri dell'elenco di seguito.
  • Prompt: domande che l'agente chiederà all'utente finale se questo parametro non è stato fornito. Questo campo viene utilizzato solo se il campo Obbligatorio è selezionato. Consulta la sezione Riempimento degli slot con i parametri richiesti di seguito.
  • Valore predefinito: è il valore predefinito per il parametro quando l'utente finale non ne fornisce uno. Per modificare il valore predefinito nella console, devi passare il mouse sopra la riga del parametro e fare clic sul menu a destra.

Quando viene trovata una corrispondenza di un intent in fase di runtime, Dialogflow fornisce i dati dei parametri alla richiesta webhook di fulfillment o alla risposta di interazione dell'API. Questi vengono forniti come mappatura dai nomi dei parametri ai valori dei parametri.

Quando crei un agente, le risposte possono includere valori parametro. Consulta Valori dei parametri e riferimenti ai parametri di seguito.

Elenca parametri

Quando crei un agente con la console, se selezioni l'opzione È elenco, il parametro viene configurato come elenco. Gli elenchi possono contenere più elementi. Ad esempio, un agente di ordinazione della produzione potrebbe aspettarsi le seguenti espressioni dell'utente finale:

  • "Voglio le mele"
  • "Voglio mele e arance"
  • "Voglio mele, arance e banane"

Quando annoti frasi di addestramento con parametri di elenco, le frasi possono contenere uno o più esempi di parametri e annotali separatamente:

Screenshot dell'annotazione dei parametri dell'elenco.

Dopo aver annotato almeno due parole o frasi con lo stesso parametro in una singola frase di addestramento, l'opzione È elenco viene attivata automaticamente. Se disabiliti questa opzione, ma mantieni la stessa annotazione, il campo È elenco verrà controllato di nuovo automaticamente dopo aver aperto la pagina con questa annotazione.

Negli agenti multilingue, l'opzione È elenco non è specifica per la lingua.

Valori dei parametri e riferimenti ai parametri

I riferimenti ai parametri sono variabili che contengono i valori dei parametri estratti durante l'esecuzione. Quando crei un agente, puoi utilizzare i riferimenti ai parametri nelle risposte di intent, nei prompt dei parametri e nel campo Valore del parametro.

Ad esempio, puoi utilizzare $parameter-name in una risposta per intent. Quando Dialogflow risponde all'utente, sostituisce il riferimento al parametro con il valore parametro estratto in fase di runtime. Ciò è utile per riepilogare le informazioni fornite dall'utente finale. Ad esempio, la tua risposta intent potrebbe essere: "Ok, ho prenotato una stanza per te il giorno $date".

Riferimento parametro di base

Per fare riferimento a un valore parametro estratto dall'entità associata, utilizza il seguente formato:

$parameter-name

Ad esempio, se il nome del parametro è date, puoi farvi riferimento come $date.

Riferimento ai parametri per un valore originale

Quando il testo viene abbinato a una particolare entità, spesso viene convertito in testo più comodo per l'elaborazione. Ad esempio, la parola "mele" in un'espressione dell'utente finale può essere estratta come "mela" per un'entità frutta. Per fare riferimento a un valore parametro esattamente come è stato scritto o pronunciato dall'utente finale, utilizza il seguente formato:

$parameter-name.original

Ad esempio, se il nome del parametro è date, puoi fare riferimento al valore originale come $date.original.

Riferimento ai parametri per date ambigue

Quando un parametro è associato all'entità di sistema @sys.date e l'utente finale fornisce una data parziale (senza specificare mese, giorno e anno), Dialogflow associa la data più vicina nel futuro. Tuttavia, puoi anche recuperare le varianti di questa data.

Puoi recuperare la corrispondenza esplicita parziale, in cui Dialogflow sostituisce la parte sconosciuta con U utilizzando il seguente formato:

$parameter-name.partial

Puoi recuperare la data più vicina nel passato utilizzando il seguente formato:

$parameter-name.recent

Ad esempio, se la data di oggi è l'11 agosto 2021, il nome del parametro è date e l'utente dice "13 agosto":

Riferimento parametro Valore risolto
$date 2021-08-13
$date.partial UUUU-08-13
$date.recent 2020-08-13

Riferimento ai parametri per un'entità composita

Le entità composte sono entità che contengono altre entità secondarie. Per fare riferimento al valore della sottoentità di un parametro, utilizza il seguente formato:

$parameter-name.sub-entity-name

Ad esempio, se il nome del parametro è move e il nome dell'entità secondaria è direction, puoi fare riferimento al valore dell'entità secondaria come $move.direction.

Riferimento ai parametri per un contesto attivo

I contesti possono fungere da spazio di archiviazione temporaneo per i valori parametro. Per fare riferimento a un valore parametro ottenuto da un contesto attivo, utilizza il seguente formato:

#context-name.parameter-name

Ad esempio, se il nome del parametro è room e reservation è un contesto attivo, puoi fare riferimento al valore parametro come #reservation.room.

Riferimento per un parametro evento

Per fare riferimento a un parametro event, utilizza il seguente formato:

#event-name.parameter-name

Ad esempio, se il nome del parametro è duration e il nome dell'evento è alarm, puoi fare riferimento al parametro evento come #alarm.duration.

Campo Valore parametro

I riferimenti ai parametri nel campo Valore del parametro hanno un significato speciale. I contenuti di questo campo determinano il valore risolto per$parameter-name nelle risposte di intent e nei prompt dei parametri. Dialogflow elabora i dati dei parametri nel seguente ordine:

  1. Estrai il valore parametro dall'espressione dell'utente finale utilizzando l'entità associata.
  2. Risolvi i contenuti del campo del parametro Valore.
  3. Imposta $parameter-name sul contenuto risolto del campo Valore del parametro. Se il campo Valore non è impostato su $parameter-name, il valore di $parameter-name viene reimpostato.
  4. Risolvi i contenuti relativi alle risposte di intent e alle richieste di parametri.

Ecco alcuni esempi per illustrare gli effetti di questo ordinamento per un'espressione dell'utente finale "voglio acquistare una camicia piccola".

Posizione riferimento parametro Contenuti configurati Contenuti risolti
Campo Valore del parametro $size S
Risposta dell'intent Hai scelto la taglia: $size Hai scelto la taglia: S
Posizione riferimento parametro Contenuti configurati Contenuti risolti
Campo Valore del parametro $size.original small
Risposta dell'intent Hai scelto la taglia: $size Hai scelto la taglia: small
Posizione riferimento parametro Contenuti configurati Contenuti risolti
Campo Valore del parametro $size S
Risposta dell'intent Hai scelto la taglia: $size.original Hai scelto la taglia: small

Compilazione slot con i parametri richiesti

Quando crei un agente, puoi contrassegnare i parametri come richiesti. Un intent non è completo finché l'utente finale non ha fornito i dati per ciascuno di questi parametri obbligatori.

Screenshot dei campi dei parametri obbligatori

Quando viene abbinata un intent in fase di runtime, l'agente Dialogflow continua a raccogliere informazioni dall'utente finale finché quest'ultimo non ha fornito i dati per ciascuno dei parametri richiesti. Questa procedura è chiamata riempimento delle aree annuncio.

Dialogflow non invia una richiesta di webhook di fulfillment finché non ha raccolto tutti i dati richiesti dall'utente finale, a meno che non sia abilitato Webhook per il riempimento degli slot.

Dialogflow invia una risposta di interazione API per ogni passaggio del riempimento degli slot. Per ciascuna di queste risposte di riempimento degli slot, l'intent e l'azione saranno gli stessi e verranno forniti i parametri raccolti finora.

Quando crei un agente, fornisci i prompt che l'agente utilizzerà per ottenere i dati dei parametri dall'utente finale. Puoi anche fornire varianti dei prompt, in modo che l'agente non ponga sempre la stessa domanda.

Screenshot delle richieste di parametri

Ad esempio, l'agente del tuo negozio di abbigliamento ha un intento che prevede parametri obbligatori per:

  • tipo di abbigliamento
  • quantity
  • dimensioni
  • colore

Il completamento di un intent potrebbe avere il seguente aspetto:

Utente: voglio acquistare una t-shirt.
Agente: Quanti ne vuoi?
Utente: 3
Agente: Di che colore vorresti?
Utente: Nero
Agent: Che taglia?
Utente: media
Agent: Ok, ecco tre t-shirt nere di taglia M

Se l'utente finale fornisce dati per più parametri in una singola espressione, Dialogflow raccoglie i dati forniti e continua a chiedere i dati mancanti. Ad esempio, l'utente finale potrebbe dire "Vorrei acquistare tre t-shirt nere". Dialogflow chiede le dimensioni all'utente.

Parametri di ordinamento

Quando crei un agente, puoi ordinare i parametri, che determinano l'ordine in cui l'agente chiederà all'utente finale di visualizzare i dati mancanti.

Quando crei un agente dalla console, passa il mouse sopra un parametro per visualizzare l'icona di riordinamento sulla destra. Puoi trascinare questa icona per modificare la posizione del parametro nell'elenco.

Riferimenti ai parametri nei prompt

Quando crei un agente, puoi utilizzare i riferimenti ai parametri nei prompt, ma solo per i parametri obbligatori prima del prompt. Ad esempio, se il parametro color si trova prima del parametro quantity, puoi utilizzare il seguente prompt per il parametro quantity: How many $color t-shirts would you like to buy?

Annulla compilazione slot

Quando l'utente finale pronuncia una frase di uscita come "Annulla", "Interrompi", "È sufficiente" e così via, l'agente risponde con "OK, annullato" e cancella i contesti di riempimento degli slot.

Se utilizzi l'API, il campo DetectIntentResponse.queryResult.cancelsSlotFilling è impostato su true quando la compilazione delle aree annuncio viene annullata. Per ulteriori informazioni, consulta la documentazione detectIntent del tipo Sessions.