Creare azioni per l'Assistente Google utilizzando l'SDK Actions (livello 1)

1. Panoramica

Attenzione: le azioni di conversazione sono state ritirate il 13 giugno 2023. Per saperne di più, consulta Ritiro di Azioni conversazionali.

La piattaforma per sviluppatori dell'Assistente Google ti consente di creare software per estendere la funzionalità dell'Assistente Google, un assistente personale virtuale, su oltre 1 miliardo di dispositivi, tra cui smart speaker, smartphone, auto, TV, cuffie e altro ancora. Gli utenti interagiscono con l'assistente per svolgere attività, come fare la spesa o prenotare una corsa. In qualità di sviluppatore, puoi utilizzare la piattaforma per sviluppatori dell'assistente per creare e gestire facilmente esperienze conversazionali piacevoli ed efficaci tra gli utenti e il tuo servizio di fulfillment di terze parti.

Questo codelab illustra i concetti di base per lo sviluppo con l'SDK Actions per l'Assistente Google. Per completarlo, non è necessaria alcuna esperienza precedente con la piattaforma. In questo codelab, creerai una semplice Azione per l'Assistente Google che predice il futuro degli utenti mentre iniziano la loro avventura nella mitica terra di Gryffinberg. Nel codelab Actions SDK livello 2, sviluppi ulteriormente questa Azione per personalizzare la previsione dell'utente in base al suo input.

Cosa creerai

In questo codelab, creerai una semplice Azione con le seguenti funzioni:

• Risponde agli utenti con un messaggio di saluto
• Pone agli utenti una domanda e risponde in modo appropriato alla selezione dell'utente
• Fornisce chip di suggerimento su cui gli utenti possono fare clic per fornire input
• Modifica il messaggio di saluto all'utente in base al fatto che sia un utente di ritorno

Al termine di questo codelab, l'Azione completata avrà il seguente flusso di conversazione (il testo accanto al microfono rappresenta l'input dell'utente, mentre il testo accanto all'altoparlante rappresenta la risposta dell'Azione):

Obiettivi didattici

• Come creare un progetto nella console Actions
• Come utilizzare lo strumento gactions per eseguire il push e il pull del progetto di Azione tra la console Actions e il file system locale
• Come inviare un prompt all'utente dopo che ha richiamato l'Azione
• Come elaborare l'input di un utente e restituire una risposta
• Come testare l'Azione nel simulatore di Actions
• Come implementare il fulfillment utilizzando l'editor di Cloud Functions

Che cosa ti serve

Nel tuo ambiente devono essere presenti i seguenti strumenti:

• Un IDE o un editor di testo di tua scelta
• Un terminale per eseguire i comandi della shell per Node.js e npm
• Un browser web, ad esempio Google Chrome

Se preferisci lavorare con strumenti più visivi per creare Azioni, segui invece il codelab Crea azioni per l'Assistente Google utilizzando Actions Builder (livello 1), che crea la stessa Azione utilizzando l'IDE di Actions Builder nella console.

2. Configura

Le sezioni seguenti descrivono come configurare l'ambiente di sviluppo e creare il progetto Actions.

Verifica le impostazioni delle autorizzazioni Google

Per testare l'Azione che crei in questo codelab, devi abilitare le autorizzazioni necessarie in modo che il simulatore possa accedere alla tua Azione.

Per attivare le autorizzazioni, segui questi passaggi:

1. Vai a Gestione attività.
2. Se non l'hai ancora fatto, accedi con il tuo Account Google.
3. Attiva le seguenti autorizzazioni:

• Attività web e app
• In Attività web e app, seleziona la casella di controllo Includi la cronologia di Chrome e le attività svolte su siti, app e dispositivi che usano i servizi Google.

crea un progetto Actions

Il progetto Actions è un container per la tua Azione.

Per creare il progetto di Actions per questo codelab, segui questi passaggi:

1. Apri la Console Actions.
2. Fai clic su Nuovo progetto.
3. Inserisci un Nome progetto, ad esempio actions-codelab. Il nome è solo per riferimento interno. In un secondo momento, puoi impostare un nome esterno per il progetto.

4. Fai clic su Crea progetto.
5. Nella schermata Che tipo di azione vuoi creare?, seleziona la scheda Personalizzata.
6. Fai clic su Avanti.
7. Nella schermata Come vuoi crearlo?, seleziona la scheda Progetto vuoto.
8. Fai clic su Inizia a creare.

Salva l'ID progetto per l'Azione

L'ID progetto è un identificatore univoco dell'Azione. L'ID progetto ti servirà per diversi passaggi di questo codelab.

Per recuperare l'ID progetto, segui questi passaggi:

1. Nella console Actions, fai clic sui tre puntini verticali (inserisci l'icona qui).
2. Fai clic su Impostazioni progetto.

3. Copia l'ID progetto.

Associa un account di fatturazione

Se non hai ancora un account di fatturazione, devi crearne uno e associarlo al tuo progetto in Google Cloud per eseguire il deployment del fulfillment in un secondo momento con Cloud Functions.

Per associare un account di fatturazione al tuo progetto, segui questi passaggi:

1. Vai alla pagina di fatturazione di Google Cloud Platform.
2. Fai clic su Aggiungi account di fatturazione o Crea account.
3. Inserisci i dati di pagamento.
4. Fai clic su Inizia la prova senza costi o Invia e abilita la fatturazione.
5. Vai alla pagina di fatturazione di Google Cloud Platform.
6. Fai clic sulla scheda I miei progetti.
7. Fai clic sui tre puntini sotto Azioni accanto al progetto Actions per il codelab.
8. Fai clic su Cambia fatturazione.
9. Nel menu a discesa, seleziona l'account di fatturazione che hai configurato.
10. Fai clic su Imposta account.

Per evitare che ti vengano addebitati costi, segui i passaggi nella sezione Esegui la pulizia del progetto alla fine di questo codelab.

Installa l'interfaccia a riga di comando gactions

In questo codelab, utilizzerai lo strumento di interfaccia a riga di comando (CLI) gactions per sincronizzare il progetto Actions tra la console Actions e il file system locale.

Termine chiave:

• Interfaccia a riga di comando gactions: uno strumento che ti consente di inizializzare i file di progetto di Actions, eseguire il push degli aggiornamenti alla console Actions, eseguire il deployment dei progetti di Actions e altro ancora.

Per installare l'interfaccia a riga di comando gactions, segui le istruzioni riportate in Installa lo strumento a riga di comando gactions.

Scarica il progetto Actions

Inizia a sviluppare l'Azione scaricando il progetto di Actions dalla console Actions.

Per scaricare il progetto di Actions, segui questi passaggi:

1. Per creare una nuova directory e passare a questa directory, esegui questi comandi:

mkdir myproject
cd myproject

2. Per copiare la configurazione del progetto Actions nel file system locale, esegui questo comando:

gactions pull --project-id <projectID>

Informazioni sulla struttura del file

Il progetto Actions scaricato dalla console Actions è rappresentato in una struttura di file YAML. L'immagine seguente mostra una rappresentazione di alto livello della struttura dei file:

La struttura del file è la seguente:

• actions/: rappresenta il tuo progetto Actions. Il sistema chiama actions.yaml quando viene richiamata l'Azione, che a sua volta chiama il file custom/global/actions.intent.MAIN.yaml.
• custom/: la directory in cui lavorerai per modificare l'Azione.
• global/: questa directory contiene gli intent di sistema che la piattaforma aggiunge automaticamente al tuo progetto. Scoprirai di più sugli intent di sistema più avanti in questo codelab.
• manifest.yaml: un file che contiene informazioni trasportabili o non specifiche di un determinato progetto e che possono essere spostate tra i progetti.
• settings/: rappresenta le impostazioni di un progetto Actions, come il nome visualizzato, le impostazioni internazionali predefinite e la categoria.

3. Avvia una conversazione

Gli utenti avviano la conversazione con la tua Azione tramite l'invocazione. Ad esempio, se hai un'Azione denominata MovieTime, gli utenti possono richiamarla dicendo una frase come "Hey Google, parla con MovieTime", dove MovieTime è il nome visualizzato. Per eseguire il deployment in produzione, l'Azione deve avere un nome visualizzato. Tuttavia, per testarla, non è necessario definirlo. Puoi invece utilizzare la frase "Parla con la mia app di test" nel simulatore per richiamare l'Azione. Scoprirai di più sul simulatore più avanti in questa sezione.

Devi modificare l'invocazione principale per definire cosa succede dopo che un utente richiama l'Azione.

Termine chiave:

• Chiamata principale: un punto di contatto per consentire agli utenti di avviare conversazioni con l'Azione. Quando gli utenti pronunciano una frase simile a "Hey Google, fammi parlare con <nome visualizzato>", l'invocazione principale si attiva e risponde all'utente.

Per impostazione predefinita, l'Azione fornisce un prompt generico quando viene attivato l'intent di chiamata ("Start building your Action by defining main invocation.").

Termine chiave:

• Prompt: definisce ciò che l'Azione invia agli utenti come risposta. I prompt possono essere semplici risposte di testo e vocali o messaggi avanzati, come schede e immagini.

Puoi utilizzare un prompt speciale, Canvas, per restituire all'utente immagini a schermo intero. Per ulteriori informazioni su Canvas, consulta la documentazione di Interactive Canvas.

Nella sezione successiva, personalizzerai il prompt per l'invocazione principale nel file custom/global/actions.intent.MAIN.yaml.

Configura l'invocazione principale

Puoi modificare il prompt di chiamata principale nel file actions.intent.MAIN.yaml.

Per modificare il prompt che l'Azione invia all'utente quando richiama l'Azione, segui questi passaggi:

1. Apri custom/global/actions.intent.MAIN.yaml nell'editor di testo.
2. Sostituisci il testo nel campo speech (Start building your action...) con il seguente messaggio di benvenuto: A wondrous greeting, adventurer! Welcome to the mythical land of Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you're on your way to an epic journey.

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: A wondrous greeting, adventurer! Welcome to the mythical land of 
                Gryffinberg! Based on your clothes, you are not from around these lands. 
                It looks like you're on your way to an epic journey.
transitionToScene: actions.scene.END_CONVERSATION

3. Salva il file.

Testa l'intent di chiamata principale nel simulatore

La console Actions fornisce uno strumento web per testare l'Azione, chiamato simulatore. L'interfaccia simula i dispositivi hardware e le relative impostazioni, in modo che tu possa interagire con l'Azione come se fosse in esecuzione su uno smart display, uno smartphone, uno speaker o KaiOS.

Per le informazioni più recenti sull'utilizzo del simulatore della console Actions o se riscontri problemi nei passaggi seguenti, consulta la pagina Simulatore.

Quando richiami l'Azione, ora dovrebbe rispondere con il prompt personalizzato che hai aggiunto ("Un saluto meraviglioso, avventuriero!…").

Puoi utilizzare il comando gactions deploy preview per testare l'Azione nella console senza aggiornare la versione del progetto di Azioni. Quando esegui questo comando, nessuna delle modifiche apportate nel file system locale viene propagata alle versioni di cui è stato eseguito il deployment del progetto Actions, ma puoi testarle in una versione di anteprima.

Per testare l'invocazione principale dell'Azione nel simulatore, segui questi passaggi:

1. Per eseguire il deployment del progetto nella console Actions per i test, esegui questo comando nel terminale:

gactions deploy preview

Quando esegui questo comando, potresti ricevere una notifica di problemi di convalida. Se i file sono stati inviati, puoi ignorare questa notifica.

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Per richiamare l'Azione nel simulatore, digita Talk to my test app nel campo Input e premi Enter.

Suggerimento: puoi anche fare clic sul chip di suggerimento Parla con la mia app di test in Suggerimenti, che viene elaborato allo stesso modo dell'input utente vocale o digitato.

In alternativa, puoi fare clic sull'icona del microfono e dire "Parla con la mia app di test" per richiamare l'Azione.

Quando attivi l'intent di chiamata principale dell'Azione, l'assistente risponde con il tuo messaggio di benvenuto personalizzato. A questo punto, la conversazione termina dopo che l'assistente risponde con un saluto. Nella sezione successiva, modificherai l'Azione in modo che la conversazione continui.

Visualizza i log eventi

Quando ti trovi nella scheda Test della console Actions, il riquadro mostra i log eventi, che mostrano la cronologia delle conversazioni come log eventi. Ogni log eventi mostra gli eventi che si verificano durante quel turno della conversazione.

Al momento l'Azione ha un log eventi, che mostra sia l'input dell'utente ("Parla con la mia app di test") sia la risposta dell'Azione. Lo screenshot seguente mostra il log eventi dell'Azione:

Se fai clic sulla Freccia giù accanto a Talk to my test app nel log eventi, puoi visualizzare gli eventi, disposti in ordine cronologico, che si sono verificati in quel turno della conversazione:

• userInput: corrisponde all'input dell'utente ("Parla con la mia app di test")
• interactionMatch: corrisponde alla risposta di chiamata principale dell'Azione, attivata dall'input dell'utente. Se espandi questa riga facendo clic sulla freccia, puoi visualizzare il prompt che hai aggiunto per l'invocazione principale (A wondrous greeting, adventurer!...)
• endConversation: corrisponde alla transizione selezionata nell'intent Main invocation, che attualmente termina la conversazione. Scoprirai di più sulle transizioni nella prossima sezione di questo codelab.

I log eventi forniscono visibilità sul funzionamento dell'Azione e sono strumenti utili per il debug dell'Azione in caso di problemi. Per visualizzare i dettagli di un evento, fai clic sulla freccia accanto al nome dell'evento, come mostrato nello screenshot seguente:

4. Crea la conversazione dell'Azione

Ora che hai definito cosa succede dopo che un utente richiama la tua Azione, puoi creare il resto della conversazione dell'Azione. Prima di continuare con questo codelab, acquisisci familiarità con i seguenti termini per capire come funziona la conversazione della tua Azione:

Termini chiave:

• Scena: un componente di base per l'Azione che elabora l'input dell'utente e in genere genera la risposta per l'utente. Gli intent personalizzati spesso attivano altre scene, ma le scene possono essere attivate anche in altri modi.
• Intento personalizzato: definisce l'input dell'utente che l'Azione può comprendere. Sei tu a definire le frasi di addestramento per questi intent. Quando gli utenti dicono qualcosa che corrisponde o è simile a una frase di addestramento, viene trovato l'intent corrispondente.
• Frasi di addestramento: esempi di ciò che un utente potrebbe dire per trovare una corrispondenza con un intent. Il motore di comprensione del linguaggio naturale (NLU) dell'assistente espande naturalmente queste frasi di addestramento per includere altre frasi simili.
• Transizione: definisce la scena a cui passare una volta soddisfatta la condizione.

L'Azione può avere una o più scene e devi attivare ogni scena prima che possa essere eseguita. L'Azione che crei in questo codelab ha una sola scena intitolata Start. Il modo più comune per attivare una scena è configurare l'Azione in modo che, quando l'input dell'utente corrisponde a un intent all'interno di una scena, l'intent attivi la transizione a un'altra scena e la attivi.

Ad esempio, immagina un'ipotetica Azione che fornisce all'utente informazioni sugli animali. Quando l'utente richiama questa Azione, viene trovata una corrispondenza con l'intent Main invocation, che attiva la transizione a una scena denominata Facts.. Questa transizione attiva la scena Facts, che invia all'utente il seguente prompt: Would you like to hear a fact about cats or dogs?. All'interno della scena Facts è presente un intent personalizzato per intenzione denominato Cat, che contiene frasi di addestramento che l'utente potrebbe pronunciare per ascoltare una curiosità sui gatti, ad esempio "Voglio ascoltare una curiosità sui gatti" o "gatto". Quando l'utente chiede di ascoltare una curiosità sui gatti, viene trovato un intent Cat corrispondente, che attiva una transizione a una scena chiamata Cat fact.. La scena Cat fact si attiva e invia all'utente un prompt che include una curiosità sui gatti.

Figura 1. Il flusso di un tipico turno di conversazione in un'Azione creata con l'SDK di Actions.

Insieme, scene, intent e transizioni costituiscono la logica della conversazione e definiscono i vari percorsi che l'utente può seguire durante la conversazione con l'Azione. Nella sezione seguente, creerai una scena e definirai come viene attivata dopo che un utente richiama la tua Azione.

Transizione dalla chiamata principale alla scena

In questa sezione, creerai una nuova scena denominata Start, che invia un prompt all'utente chiedendogli se vuole che gli venga predetto il futuro. Aggiungi anche una transizione dall'intent di chiamata principale alla nuova scena Start.

Per creare questa scena e aggiungervi una transizione, segui questi passaggi:

1. Apri custom/global/actions.intent.MAIN.yaml nell'editor di testo.
2. Sostituisci il testo nel campo transitionToScene (actions.scene.END_CONVERSATION) con il seguente: transitionToScene: Start

actions.intent.MAIN.yaml

handler:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Welcome to the mythical land of  Gryffinberg! Based on your clothes,
              you are not from around these lands. It looks like you're on your way
              to an epic journey.
transitionToScene: Start

In questo modo, l'Azione passa dalla chiamata principale alla scena Start.

3. Salva il file.
4. Nel terminale, crea una nuova directory scenes nella directory custom:

mkdir custom/scenes 

5. Crea un nuovo file denominato Start.yaml nella directory scenes, che rappresenta la scena start nell'Azione:

touch custom/scenes/Start.yaml 

6. Apri Start.yaml nell'editor di testo.
7. Incolla il seguente codice nel file Start.yaml:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?

Nel codice del file Start.yaml, è presente un campo denominato onEnter, che rappresenta la prima fase eseguita nel ciclo di vita di una scena.

Termini chiave:

• OnEnter: la fase che viene eseguita quando si attiva una scena. OnEnter definisce cosa succede quando l'utente entra nella scena.

In questo caso, il prompt (Before you continue on your quest...) viene aggiunto alla coda dei prompt quando l'utente entra per la prima volta nella scena Start.

Termini chiave:

• Coda dei prompt: i prompt vengono aggiunti uno dopo l'altro in una coda. Prima che l'utente possa rispondere, l'assistente presenta all'utente tutti i prompt nella coda dei prompt.

Aggiungi chip di suggerimento

I chip di suggerimento offrono suggerimenti cliccabili per l'utente che l'Azione elabora come input dell'utente. In questa sezione, aggiungi i chip di suggerimento Yes e No che vengono visualizzati sotto il prompt appena configurato (Before you continue on your quest, would you like your fortune told?) per supportare gli utenti su dispositivi con schermo.

Per aggiungere chip di suggerimento al prompt della scena Start, segui questi passaggi:

1. Aggiorna il codice in Start.yaml in modo che corrisponda al seguente snippet di codice, che include il codice per la configurazione dei chip di suggerimento:

Start.yaml

onEnter:
  staticPrompt:
    candidates:
    - promptResponse:
        firstSimple:
          variants:
          - speech: Before you continue on your quest, would you like your fortune
              told?
        suggestions:
        - title: "Yes"
        - title: "No"

2. Salva il file.

Testa l'Azione nel simulatore

A questo punto, l'Azione dovrebbe passare dall'intent di chiamata principale alla scena Start e chiedere all'utente se vuole che gli venga predetto il futuro. I chip di suggerimento dovrebbero essere visualizzati anche nel display simulato.

Per testare l'Azione nel simulatore, segui questi passaggi:

1. Nel terminale, esegui questo comando:

gactions deploy preview

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Fai clic su Test per accedere al simulatore.
4. Digita Talk to my test app nel campo Input e premi Enter. L'Azione dovrebbe rispondere con il prompt Main invocation e il prompt della scena Start aggiunto, "Prima di continuare la tua missione, vuoi che ti legga il futuro?", con i chip di suggerimento visualizzati.

Lo screenshot seguente mostra questa interazione:

I log eventi registrano ogni interazione del simulatore nella sessione corrente, quindi il log eventi dei test precedenti in questo codelab viene visualizzato come primo log eventi. Per cancellare i log eventi, fai clic su Reimposta test.

5. Fai clic sul chip di suggerimento Sì o No per rispondere al prompt. Puoi anche dire "Sì" o "No" o inserire Yes o No nel campo Input.

Quando rispondi al prompt, l'Azione risponde con un messaggio che indica che non riesce a capire il tuo input: "Mi dispiace, non ho capito. Puoi provare di nuovo?" Poiché non hai ancora configurato l'Azione per comprendere e rispondere all'input "Sì" o "No", l'Azione abbina l'input a un intent NO_MATCH.

Termini chiave:

• NO_MATCH: un intent generico che viene abbinato quando l'utente dice qualcosa che non può essere abbinato a un altro intent nella tua Azione.
• Intent di sistema: un intent configurato per impostazione predefinita che gestisce gli eventi di sistema comuni, ad esempio quando un utente non fornisce input. NO_MATCH e l'intent legato all'intent di chiamata principale sono esempi di intent di sistema.

Per impostazione predefinita, l'intent di sistema NO_MATCH fornisce risposte generiche, ma puoi personalizzarle per indicare all'utente che non hai capito il suo input. L'assistente termina la conversazione dell'utente con la tua azione dopo che non riesce ad abbinare l'input dell'utente per tre volte.

Aggiungi gli intent yes e no

Ora che gli utenti possono rispondere alla domanda posta dall'Azione, puoi configurare l'Azione in modo che comprenda le risposte degli utenti ("Sì" o "No"). Nelle sezioni seguenti, creerai intent personalizzati che vengono abbinati quando l'utente dice "Sì" o "No" e aggiungerai questi intent alla scena Start.

Crea l'intent yes

Per creare l'intent yes, segui questi passaggi:

1. Nel terminale, crea una nuova directory denominata intents nella directory custom:

mkdir custom/intents 

2. Crea un nuovo file denominato yes.yaml nella directory intents:

touch custom/intents/yes.yaml

3. Apri yes.yaml nell'editor di testo.
4. Incolla il seguente snippet di codice contenente le frasi di addestramento in yes.yaml:

yes.yaml

trainingPhrases:
- of course
- let's do it
- ok
- sure
- "y"
- "yes"

5. Salva il file.

Aggiungi l'intent yes alla scena Start

Ora l'Azione può capire quando un utente esprime un intento "sì". Puoi aggiungere l'intent personalizzato yes alla scena Start, poiché l'utente sta rispondendo al prompt Start ("Prima di continuare la tua missione, vuoi che ti legga il futuro?").

Per aggiungere questo intent personalizzato alla scena Start, segui questi passaggi:

1. Apri custom/scenes/Start.yaml nell'editor di testo.
2. Aggiungi il gestore intentEvents e yes alla fine del file Start.yaml:

Start.yaml

intentEvents:
- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: Your future depends on the item you choose to use for your quest. Choose wisely! Farewell, stranger.
  intent: "yes"
  transitionToScene: actions.scene.END_CONVERSATION

Quando viene rilevato l'intent yes, il prompt "Il tuo futuro dipende dall'oggetto che scegli di utilizzare per la tua missione…" viene aggiunto alla coda dei prompt. La scena Start passa poi alla scena di sistema actions.scene.END_CONVERSATION, che fornisce i prompt nella coda dei prompt e termina la conversazione.

Testa l'intent yes nel simulatore

A questo punto, l'Azione comprende quando l'utente vuole conoscere il proprio futuro e restituisce la risposta appropriata.

Per testare questo intent nel simulatore, segui questi passaggi:

1. Nel terminale, esegui questo comando:

gactions deploy preview

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Fai clic su Test per accedere al simulatore.
4. Per testare l'Azione nel simulatore, digita Talk to my test app nel campo Input e premi Enter.
5. Digita Yes nel campo Input e premi Enter. In alternativa, fai clic sul chip di suggerimento Sì.

L'Azione risponde all'utente e gli dice che la sua fortuna dipende dall'aiuto che sceglie. L'Azione termina quindi la sessione perché hai configurato la transizione End conversation per l'intent yes.

Crea l'intent no

Ora puoi creare l'intent no in modo che l'Azione possa capire e rispondere all'utente quando non vuole ascoltare la sua previsione.

Per creare questo intent, segui questi passaggi:

1. Nel terminale, crea un nuovo file denominato no.yaml nella directory intents:

touch custom/intents/no.yaml

2. Apri no.yaml nell'editor di testo.
3. Incolla le seguenti frasi di addestramento nel file no.yaml:

no.yaml

trainingPhrases:
- nope
- I don't want
- "n"
- "no"
- nah
- no thanks

4. Salva il file.

Aggiungi l'intent no alla scena Start

Ora l'Azione può capire quando un utente esprime un "no" o qualcosa di simile a "no", ad esempio "no, grazie". Devi aggiungere l'intent personalizzato no alla scena Start perché l'utente sta rispondendo al prompt Start ("Prima di continuare la tua missione, vuoi che ti legga il futuro?").

Per aggiungere questo intent per la scena Start, segui questi passaggi:

1. Apri custom/scenes/Start.yaml nell'editor di testo.
2. Aggiungi il seguente gestore no sotto il gestore yes in Start.yaml:

Start.yaml

- handler:
    staticPrompt:
      candidates:
      - promptResponse:
          firstSimple:
            variants:
            - speech: I understand, stranger. Best of luck on your quest! Farewell.
  intent: "no"
  transitionToScene: actions.scene.END_CONVERSATION

3. Salva il file.

Testa l'intent no nel simulatore

A questo punto, l'Azione capisce quando l'utente non vuole ascoltare la sua previsione e restituisce la risposta appropriata.

Per testare questo intent nel simulatore, segui questi passaggi:

1. Nel terminale, esegui questo comando:

gactions deploy preview

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Fai clic su Test per accedere al simulatore.
4. Digita Talk to my test app nel campo Input e premi Enter.
5. Digita No nel campo Input e premi Enter. In alternativa, fai clic sul chip di suggerimento No.

Anziché rivelare il futuro all'utente, l'Azione gli augura buona fortuna per il suo viaggio. L'Azione termina quindi la sessione perché hai configurato la transizione End conversation per l'intent no.

5. Implementa il fulfillment

Al momento, le risposte dell'Azione sono statiche; quando viene attivata una scena contenente un prompt, l'Azione invia ogni volta lo stesso prompt. In questa sezione, implementerai il fulfillment che contiene la logica per creare una risposta conversazionale dinamica.

Termine chiave:

• Fulfillment: il codice che contiene la logica per l'Azione. Un webhook attiva le chiamate al tuo fulfillment in base agli eventi che si verificano all'interno delle tue azioni.

Il fulfillment identifica se l'utente è un utente di ritorno o un nuovo utente e modifica il messaggio di saluto dell'Azione per gli utenti di ritorno. Il messaggio di saluto è più breve per gli utenti di ritorno e riconosce il loro ritorno: "Un saluto meraviglioso, avventuriero! Ti diamo il bentornato nella mitica terra di Gryffinberg!"

Per questo codelab, utilizzerai l'editor di Cloud Functions per modificare ed eseguire il deployment del codice di fulfillment.

Termine chiave:

• Editor di Cloud Functions: un editor integrato per i progetti Actions, che puoi utilizzare per modificare ed eseguire il deployment del codice di fulfillment utilizzando Cloud Functions for Firebase.

L'Azione può attivare webhook che notificano al fulfillment un evento che si verifica durante un'invocazione o parti specifiche dell'esecuzione di una scena. Quando viene attivato un webhook, l'Azione invia una richiesta con un payload JSON al fulfillment, insieme al nome del gestore da utilizzare per elaborare l'evento. Questo gestore esegue una logica e restituisce una risposta JSON corrispondente.

Crea il tuo fulfillment

In questa sezione, modifichi il fulfillment per generare prompt diversi per gli utenti di ritorno e i nuovi utenti quando richiamano l'Azione.

Per aggiungere questa logica al fulfillment, segui questi passaggi:

1. Nel terminale, assicurati di trovarti nella directory root del progetto e crea una nuova directory webhooks:

mkdir webhooks 

2. Crea un nuovo file denominato ActionsOnGoogleFulfillment.yaml nella directory webhooks:

touch webhooks/ActionsOnGoogleFulfillment.yaml

3. Apri ActionsOnGoogleFulfillment.yaml nell'editor di testo.
4. Aggiungi il gestore greeting e i contenuti inlineCloudFunction al file ActionsOnGoogleFulfillment.yaml:

ActionsOnGoogleFulfillment.yaml

handlers:
- name: greeting
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment

Il file ActionsOnGoogleFulfillment.yaml definisce i gestori del webhook (come il gestore greeting) e indica all'Azione di utilizzare Cloud Functions come endpoint del webhook.

5. Crea una nuova directory ActionsOnGoogleFulfillment nella directory webhooks:

mkdir webhooks/ActionsOnGoogleFulfillment

6. Crea un nuovo file denominato index.js nella directory ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/index.js

7. Apri index.js nell'editor di testo.
8. Aggiungi il codice seguente a index.js:

index.js

const { conversation } = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation({debug: true});

app.handle('greeting', conv => {
 let message = 'A wondrous greeting, adventurer! Welcome back to the mythical land of Gryffinberg!';
 if (!conv.user.lastSeenTime) {
   message = 'Welcome to the mythical land of  Gryffinberg! Based on your clothes, you are not from around these lands. It looks like you\'re on your way to an epic journey.';
 }
 conv.add(message);
});


exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);

Questo codice definisce il gestore greeting, che invia il saluto appropriato al

utente.

9. Salva il file.
10. Crea un nuovo file denominato package.json nella directory ActionsOnGoogleFulfillment:

touch webhooks/ActionsOnGoogleFulfillment/package.json

Il file package.json specifica le dipendenze e altri metadati per il webhook.

11. Apri package.json nell'editor di testo.
12. Copia il codice da questo repository GitHub e incollalo nel file package.json.
13. Salva il file.

comprendi il codice

Il fulfillment, che utilizza la libreria di fulfillment di Actions on Google per Node.js, risponde alle richieste HTTP dell'Assistente Google.

Nello snippet di codice precedente, definisci il gestore greeting, che controlla se l'utente ha già visitato l'Azione con la proprietà lastSeenTime. Se la proprietà lastSeenTime non è definita, l'utente è nuovo e riceve il messaggio di benvenuto destinato ai nuovi utenti. In caso contrario, il messaggio riconosce il ritorno dell'utente e genera un saluto modificato.

Aggiorna l'intent di chiamata principale per attivare un webhook

Ora che hai definito la funzione greeting, puoi configurare il gestore di eventi greeting nell'intent di chiamata principale in modo che l'Azione sappia di dover chiamare questa funzione quando l'utente la richiama.

Per configurare l'Azione in modo che chiami il nuovo gestore greeting, segui questi passaggi:

1. Apri custom/global/actions.intent.MAIN.yaml nell'editor di testo.
2. Sostituisci il codice in actions.intent.MAIN.yaml con il seguente codice:

actions.intent.MAIN.yaml

handler:
  webhookHandler: greeting
transitionToScene: Start

3. Salva il file.

Ora, quando viene trovato un intento di chiamata principale corrispondente, viene chiamato il gestore del webhook greeting.

Testa l'invocazione principale aggiornata nel simulatore

Per testare l'Azione nel simulatore, segui questi passaggi:

1. Nel terminale, esegui questo comando:

Poiché questo comando esegue il deployment del webhook e installa le dipendenze, potrebbe richiedere più tempo rispetto ai comandi precedenti.

gactions deploy preview

Se ricevi un errore 403 relativo all'API Cloud Build o un errore 403 relativo all'associazione del tuo account di fatturazione, consulta Abilita, disabilita o modifica la fatturazione per un progetto. Per eseguire il deployment utilizzando Cloud Functions, devi associare un account di fatturazione al tuo progetto in Google Cloud. Dopo aver associato un account di fatturazione, esegui di nuovo gactions deploy preview. Per evitare che ti vengano addebitati costi, segui i passaggi nella sezione Esegui la pulizia del progetto alla fine di questo codelab.

Dovresti ricevere un output simile al seguente:

✔ Done. You can now test your changes in Simulator with this URL: http://console.actions.google.com/project/{project-id}/simulator?disableAutoPreview

2. Copia l'URL fornito e incollalo in un browser.
3. Per testare l'Azione nel simulatore, digita Talk to my test app nel campo Input e premi Enter.

Poiché hai testato l'Azione in precedenza in questo codelab, non sei un nuovo utente, quindi ricevi il seguente saluto abbreviato: "Un saluto meraviglioso, avventuriero! Bentornati nella mitica terra di Gryffinberg!…"

6. Visualizza l'azione con Actions Builder

L'SDK Actions è interoperabile con un IDE basato sul web chiamato Actions Builder, integrato nella console Actions. Puoi eseguire il push del file system locale nella bozza dell'Azione nella console con il comando gactions push. A differenza di gactions deploy preview, che ti consente di testare l'Azione solo nel simulatore, gactions push sposta tutti i contenuti dai file locali ad Actions Builder.

La console Actions fornisce una rappresentazione visiva della configurazione dell'Azione. Visualizzare la tua azione mappata visivamente può essere utile durante lo sviluppo e non influisce sulla versione dell'azione pubblicata per i test.

L'esecuzione di gactions push sovrascrive la bozza corrente del progetto Actions se stai lavorando in modo collaborativo.

Per eseguire il push del progetto Actions e visualizzarlo nella console Actions, segui questi passaggi:

1. Nel terminale, esegui questo comando per eseguire il push del progetto nella console Actions:

gactions push

Dovresti ricevere un output simile al seguente:

✔ Done. Files were pushed to Actions Console, and you can now view your project with this URL: https://console.actions.google.com/project/{project-id}/overview. If you want to test your changes, run "gactions deploy preview", or navigate to the Test section in the Console.

2. Copia l'URL fornito e incollalo in un browser.
3. Nella Console Actions, fai clic su Sviluppa nella barra di navigazione in alto.
4. Fai clic sulla freccia menu a discesa accanto a Scene e poi su Avvia. Dovresti vedere una rappresentazione visiva della scena Start della tua Azione, come mostrato nello screenshot seguente:

Esegui la pulizia del progetto [consigliato]

Attenzione: il codelab di livello 2, Crea azioni per l'Assistente Google utilizzando Actions SDK (livello 2), si basa sul progetto che hai creato in questo codelab. Se prevedi di eseguire il codelab di livello 2, non eliminare il progetto, ma eliminalo nella sezione "Esegui la pulizia del progetto" alla fine del codelab di livello 2.

Per evitare possibili addebiti, ti consigliamo di rimuovere i progetti che non intendi utilizzare. Per eliminare i progetti che hai creato in questo codelab, segui questi passaggi:

1. Per eliminare il progetto Cloud e le risorse, completa i passaggi elencati nella sezione Chiusura (eliminazione) dei progetti.

Assicurati di selezionare il progetto corretto da eliminare nella pagina Impostazioni di Google Cloud Platform.

2. (Facoltativo) Per rimuovere immediatamente il progetto dalla console di Actions, completa i passaggi elencati nella sezione Elimina un progetto. Se non completi questo passaggio, il progetto viene rimosso automaticamente dopo circa 30 giorni.

7. Complimenti!

Conosci i concetti di base della creazione di azioni per l'Assistente Google con l'SDK Actions.

Argomenti trattati

• Come configurare un progetto Actions nella console Actions
• Come utilizzare l'SDK di Actions per creare il progetto di Actions nel file system locale
• Come aggiungere un prompt all'invocazione principale in modo che gli utenti possano avviare una conversazione con l'Azione
• Come creare un'interfaccia di conversazione con scene, intenti, transizioni, chip di suggerimento e fulfillment
• Come testare l'Azione con il simulatore di Actions

Scopri di più

Consulta le seguenti risorse per scoprire di più sulla creazione di Azioni per l'Assistente Google:

• Il sito ufficiale della documentazione per lo sviluppo di azioni per l'Assistente Google
• Pagina GitHub di Actions on Google per codice campione e librerie
• La community ufficiale di Reddit per gli sviluppatori che lavorano con l'assistente

Segui @ActionsOnGoogle su Twitter per gli annunci più recenti e twitta con #AoGDevs per condividere ciò che crei.

Sondaggio di feedback

Prima di andare, compila un breve sondaggio sulla tua esperienza.