Intent integrati (Dialogflow)

Un intent integrato è un identificatore univoco che puoi specificare per comunicare all'Assistente Google che l'Azione può soddisfare una categoria specifica di richieste degli utenti. Ad esempio, ecco alcuni esempi di query dell'utente che l'assistente abbina agli intent integrati:

  • Intent integrato"Gioca": "Hey Google. Fai un gioco di memoria"
  • Intent integrato"Ottieni oroscopo": "Hey Google, Prendi il mio oroscopo"

Durante il rilevamento dell'azione, l'assistente può utilizzare i metadati relativi all'azione, inclusi gli intent integrati che hai specificato, per consigliare l'azione agli utenti. Per ridurre al minimo i round trip conversazionali, l'assistente tenta anche di analizzare i parametri dalle query degli utenti e di trasmetterli all'Azione.

Per visualizzare l'elenco completo degli intent integrati supportati dall'assistente, inclusi i relativi parametri e le query degli utenti di esempio, consulta la documentazione di riferimento per gli intent integrati.

Integra intent integrati

A seconda di come stai creando l'Azione, sono disponibili diversi modi per integrare gli intent integrati.

Dialogflow

Se utilizzi Dialogflow per creare l'azione, puoi collegare graficamente un intent integrato dalla console Dialogflow.

Per collegare un intent integrato con Dialogflow, segui questi passaggi:

  1. Apri la console di Dialogflow, seleziona l'agente e vai alla schermata Intent.
  2. Crea o seleziona l'intent che l'agente attiva quando riceve un intent integrato specifico. Apri la sezione Eventi e fai clic su Aggiungi evento.

    Figura 1. Aggiunta di un evento Dialogflow nella console di Dialogflow.
  3. Nel campo Eventi, digita il nome di un evento di intent integrato per l'agente (ad esempio, actions_intent_PLAY_GAME).

    Figura 2. Collegamento di un intent integrato all'agente nella console Dialogflow.
  4. Fai clic su Salva.

SDK Actions

Se usi l'SDK Actions per creare l'azione, devi specificare la mappatura tra intent integrati e azioni nel pacchetto Azioni.

Per collegare un intent integrato con l'SDK Actions, segui questi passaggi:

  1. Specifica l'intent integrato nel campo del nome nella definizione dell'azione.
  2. Carica il pacchetto azioni nel tuo progetto Actions utilizzando lo strumento gactions, come descritto nella panoramica dell'SDK Actions.

Ad esempio, lo snippet seguente mostra come aggiungere l'intent integrato CHECK_AIR_QUALITY:

{
   "actions":[
      {
         "description":"Default Welcome Intent",
         "name":"MAIN",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.MAIN"
         }
      },
      {
         "description":"Check Air Quality",
         "name":"CHECK_AIR_QUALITY",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.CHECK_AIR_QUALITY"
         }
      }
   ],
   "conversations":{
      "conversation_1":{
         "name":"conversation_1",
         "url":"https://example.com/fulfillment",
         "fulfillmentApiVersion":2
      }
   }
}

Gestire i parametri di intent integrati

Quando l'Azione viene richiamata tramite un intent integrato, il fulfillment potrebbe ricevere parametri aggiuntivi. Lo schema di intent definisce i nomi dei parametri e i relativi tipi come tipi primitivi o entità schema.org. Per visualizzare lo schema per gli intent integrati di tipo Azione conversazionale, consulta la documentazione di riferimento per gli intent integrati.

I parametri per gli intent integrati sono facoltativi. L'assistente gestisce il riempimento dei parametri con valori se possono essere estratti dalla chiamata dell'intent integrato da parte dell'utente.

Ad esempio, lo schema dell'intent integrato actions.intent.CHECK_AIR_QUALITY definisce quattro parametri facoltativi:

Nome parametro Tipo
attributes Un valore stringa.
location Un oggetto schema.org/Place.
temporalCoverage Un oggetto schema.org/Duration.
timeIndicator Un'EnumeratedDuration (estensione specifica di Google).

Il seguente snippet di codice mostra un esempio di richiesta webhook di conversazione (JSON) quando un utente richiama l'azione dicendo "Qual è la qualità dell'aria a San Francisco domani?":

"inputs":[
      {
         "intent":"actions.intent.CHECK_AIR_QUALITY",
         "rawInputs":[
            {
               "inputType":"VOICE",
               "query":"what is the air quality in san francisco tomorrow"
            }
         ],
         "arguments":[
            {
               "name":"location",
               "structuredValue":{
                  "geo":{
                     "longitude":-122.41941550000001,
                     "latitude":37.7749295
                  },
                  "@context":"https://schema.org",
                  "@type":"Place",
                  "name":"san francisco"
               }
            },
            {
               "name":"temporalCoverage",
               "rawText":"2018-04-25",
               "textValue":"2018-04-25"
            }
         ]
      }
   ]

In questo esempio, i parametri assumono i seguenti valori:

  • Il parametro location contiene il valore schema.org/Place di "San Francisco".
  • Il parametro temporalCoverage contiene il valore schema.org/Duration per la data di domani rispetto all'ora della chiamata.
  • Non esistono valori per i parametri attributes e timeIndicator perché la frase di chiamata dell'utente non includeva queste informazioni.

Se utilizzi Azioni nella libreria client di Google per Node.js, puoi recuperare il valore dei parametri come mostrato nel seguente snippet:

app.intent('actions.intent.CHECK_AIR_QUALITY', (conv) => {
  const attributes = conv.arguments.get('attributes');
  const location = conv.arguments.get('location');
  const temporal_coverage = conv.arguments.get('temporalCoverage');
  Const time_indicator = conv.arguments.get('timeIndicator')

  // Your Action logic. If you need to use any of the parameter values,
  // you should check first that it is defined. Arguments.get returns
  // undefined if it can't find a value for a parameter.

});

Testare le integrazioni con intent integrati

Per testare l'integrazione, procedi nel seguente modo:

  1. Apri il simulatore di Azioni con l'Azione di test abilitata, oppure apri l'assistente sul tuo dispositivo.
  2. Pronuncia o digita una query associata all'intent integrato. Ad esempio, "Voglio giocare".
  3. Cerca l'Azione nella finestra di dialogo di selezione dell'app visualizzata.
  4. Seleziona l'app per inviare un intent all'app.
Figura 3. La finestra di dialogo di selezione dell'azione risultante
da una frase di intent integrata.
Figura 4. Richiamare un'Azione collegata a un intent integrato.

Best practice per l'utilizzo di intent integrati

Quando utilizzi gli intent integrati, dovresti seguire queste best practice:

  • Mappa gli intent integrati ad azioni specifiche: quando un intent integrato specifico attiva l'Azione, indirizza l'utente all'intent e alla funzionalità specifici dell'Azione con il minimo sforzo possibile. Ad esempio, se l'Azione supporta l'intent integrato di PLAY_GAME e riceve questo intent, devi indirizzare immediatamente l'utente alla funzionalità di gioco dell'Azione. Evita di chiedere di nuovo all'utente se vuole giocare.
  • Gestisci i parametri degli intent integrati: assicurati di utilizzare i valori dei parametri degli intent integrati che l'assistente invia al tuo fulfillment. Evita di chiedere nuovamente all'utente questi valori.