Azioni e parametri

Questa pagina descrive le impostazioni di azioni e parametri per gli intent e come vengono utilizzate quando gli intent vengono abbinati in fase di runtime.

Dove trovare questi dati

Quando crei un agente, è più comune utilizzare la console di Dialogflow ES (consulta la documentazione, apri la console). Le istruzioni riportate di seguito si concentrano sull'utilizzo della console. Per accedere ai dati di azioni e parametri:

1. Vai alla console di Dialogflow ES.
2. Select an agent.
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.

Se crei un agente utilizzando l'API anziché la console, consulta il riferimento agli intent. I nomi dei campi API sono simili ai nomi dei campi della console. Le istruzioni riportate di seguito evidenziano eventuali differenze importanti tra la console e l'API.

Azioni

Il campo azione è un semplice campo di convenienza che aiuta a eseguire la logica nel tuo servizio.

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

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

Parametri

Quando un intent viene abbinato 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 come vengono estratti i dati. A differenza dell'input utente finale non elaborato, i parametri sono dati strutturati che possono essere facilmente utilizzati per eseguire una logica o generare risposte.

Quando crei un agente, controlli la modalità di estrazione dei dati annotando le parti delle frasi di addestramento e configurando i parametri associati.

Il seguente elenco mostra i campi di una configurazione dei parametri. Vengono mostrati esempi per la frase di addestramento "book a room on Tuesday", in cui "Tuesday" è annotato.

• Obbligatorio: Seleziona questa casella se il parametro è obbligatorio per il completamento dell'intent. Consulta la sezione Riempimento degli slot con parametri obbligatori 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, questo valore è impostato su un riferimento al parametro come $parameter-name, che viene utilizzato come segnaposto per il valore estratto in fase di runtime. 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 come elenco. Consulta la sezione Parametri elenco di seguito.
• Prompts: domande che l'agente porrà all'utente finale se questo parametro non è stato fornito. Questo campo viene utilizzato solo se il campo Required è selezionato. Consulta la sezione Riempimento degli slot con parametri obbligatori di seguito.
• Valore predefinito: Questo è il valore predefinito del parametro quando l'utente finale non ne fornisce uno. Per modificare il valore predefinito con la console, devi passare il mouse sopra la riga del parametro e fare clic sul menu a destra.

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

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

Parametri elenco

Quando crei un agente con la console, la selezione dell'opzione Is List configura il parametro come elenco. Gli elenchi possono contenere più elementi. Ad esempio, un agente di ordinazione di prodotti potrebbe prevedere le seguenti espressioni dell'utente finale:

• "I want apples"
• "I want apples and oranges"
• "I want apples, oranges, and bananas"

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

Una volta annotate almeno due parole o frasi con lo stesso parametro in una singola frase di addestramento, l'opzione Is List viene attivata automaticamente. Se disattivi questa opzione, ma mantieni la stessa annotazione, Is List verrà selezionata automaticamente quando apri la pagina con questa annotazione.

Negli agenti multilingue, l'opzione Is List non è specifica della lingua.

Valori dei parametri e riferimenti ai parametri

I riferimenti ai parametri sono variabili che contengono i valori dei parametri estratti in fase di runtime. Quando crei un agente, puoi utilizzare i riferimenti ai parametri nelle risposte degli intent, nei prompt dei parametri e nel campo Value dei parametri.

Ad esempio, puoi utilizzare $parameter-name in una risposta dell'intent. Quando Dialogflow risponde all'utente, sostituisce il riferimento al parametro con il valore parametro estratto in fase di runtime. Questo è utile per riepilogare le informazioni fornite dall'utente finale. Ad esempio, la risposta dell'intent potrebbe essere: "Okay, I booked a room for you on $date".

Riferimento al 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 al parametro per un valore originale

Quando il testo viene abbinato a una determinata entità, viene spesso convertito in testo più comodo per l'elaborazione. Ad esempio, la parola "apples" in un'espressione dell'utente finale potrebbe essere estratta come "apple" per un'entità di 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 al parametro 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 esegue la corrispondenza con la data più vicina nel futuro. Tuttavia, puoi anche recuperare le varianti di questa data.

Puoi recuperare la corrispondenza parziale esplicita, 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 odierna è l'11 agosto 2021, il nome del parametro è date e l'utente dice "August 13":

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

Riferimento al parametro per un'entità composita

Le entità composite sono entità che contengono altre sottoentità. 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 della sottoentità è direction, puoi fare riferimento al valore della sottoentità come $move.direction.

Riferimento al parametro per un contesto attivo

I contesti possono fungere da spazio di archiviazione temporaneo per i valori dei parametri. 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 al parametro per un parametro evento

Per fare riferimento a un parametro evento, 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 Value dei parametri hanno un significato speciale. Il contenuto di questo campo determina il valore risolto per $parameter-name nelle risposte degli 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 il contenuto del campo Value del parametro.
3. Imposta $parameter-name sul contenuto risolto del campo Value del parametro. Se il campo Value non è impostato su $parameter-name, il valore di $parameter-name viene reimpostato su un altro valore.
4. Risolvi il contenuto delle risposte degli intent e dei prompt dei parametri.

Ecco alcuni esempi per illustrare gli effetti di questo ordine per un'espressione dell'utente finale "I want to buy a small shirt".

Posizione del riferimento al parametro	Contenuto configurato	Contenuto risolto
Campo Value del parametro	$size	S
Risposta dell'intent	You chose size: $size	You chose size: S

Posizione del riferimento al parametro	Contenuto configurato	Contenuto risolto
Campo Value del parametro	$size.original	small
Risposta dell'intent	You chose size: $size	You chose size: small

Posizione del riferimento al parametro	Contenuto configurato	Contenuto risolto
Campo Value del parametro	$size	S
Risposta dell'intent	You chose size: $size.original	You chose size: small

Riempimento degli slot con parametri obbligatori

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

Quando un intent viene abbinato 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 obbligatori. Questo processo è chiamato riempimento degli slot.

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

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.

Ad esempio, supponiamo che l'agente del tuo negozio di abbigliamento abbia un intent con parametri obbligatori per:

• tipo di indumento
• quantity
• size
• color

Il completamento di un intent potrebbe avere il seguente aspetto:

User: I'd like to buy a t-shirt.
Agent: How many do you want?
User: 3
Agent: What color would you like?
User: Black
Agent: What size?
User: Medium
Agent: Got it, that was three black t-shirts in medium

Se l'utente finale fornisce i dati per più di un parametro in una singola espressione, Dialogflow raccoglie i dati forniti e continua a chiedere i dati mancanti. Ad esempio, l'utente finale potrebbe dire "I'd like to buy three black t-shirts". Dialogflow chiederebbe all'utente la taglia.

Ordinamento dei parametri

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

Quando crei un agente dalla console, se passi il mouse sopra un parametro, a destra viene visualizzata un'icona di riordino. 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 precede il parametro quantity, puoi utilizzare il seguente prompt per il parametro quantity: How many $color t-shirts would you like to buy?

Annullamento del riempimento degli slot

Quando l'utente finale pronuncia una frase di uscita come "Cancel", "Stop it", "That's enough" e così via, l'agente risponde con "Okay, canceled" e cancella i contesti di riempimento degli slot.

Se utilizzi l'API, il campo DetectIntentResponse.queryResult.cancelsSlotFilling è impostato su true quando il riempimento degli slot viene annullato. Per ulteriori informazioni, consulta la documentazione detectIntent del Sessions tipo.