Parametri del playbook

I playbook possono accettare ed emettere informazioni di contesto utilizzando parametri definiti in modo esplicito. I parametri vengono utilizzati per memorizzare informazioni su una conversazione, ad esempio le selezioni dell'utente, i risultati delle azioni e così via. Puoi passare i valori di questi parametri tra playbook e flussi.

Dichiarazione dei parametri

Puoi definire parametri di input (lettura) e parametri di output (scrittura).

I parametri hanno un nome, una descrizione e uno dei seguenti tipi:

• Stringa
• Numero
• Booleano
• Tipo di parametro specifico dello strumento

Puoi anche specificare se un parametro è un elenco.

Parametri di input (lettura)

Per ogni playbook, puoi definire parametri di input, chiamati anche parametri di lettura, che consentono ai playbook di utilizzare i valori passati da flussi e altri playbook. Ad esempio, un playbook potrebbe ricevere il nome preferito di un utente come parametro e utilizzarlo per ringraziarlo personalmente, oppure potrebbe ricevere un identificatore dell'ordine come parametro e utilizzarlo per recuperare i dettagli dell'ordine utilizzando uno strumento.

I parametri di input sono definiti per playbook e, per impostazione predefinita, i playbook non hanno visibilità di altri tipi di parametri della console di Dialogflow CX. Quando un flusso passa a un playbook, i parametri di pagina e sessione vengono propagati al playbook se il playbook di destinazione ha un parametro di input con lo stesso nome. Per comunicare informazioni da un flusso a un playbook durante una transizione, definisci i parametri di input del playbook con lo stesso nome di un parametro di sessione o di pagina presente prima della transizione.

Nota: il playbook predefinito non accetta parametri di input. Il playbook predefinito funge da punto di ingresso per le conversazioni degli utenti, quindi non ha modo di ricevere parametri di input.

Crea esempi per controllare in che modo il valore parametro di input deve influire sulle azioni. Ad esempio, se un parametro di input deve influire sul modo in cui l'agente si riferisce all'utente, crea esempi che definiscano un valore per il parametro e poi utilizza lo stesso valore nelle azioni di espressione all'interno dell'esempio. Per maggiori dettagli, consulta la sezione relativa al passaggio dei parametri.

Parametri di output (scrittura, restituzione)

Per ogni playbook, puoi definire parametri di output, chiamati anche parametri di scrittura e parametri di restituzione, che consentono ai playbook di emettere informazioni da utilizzare in altri flussi o playbook. Ad esempio, un playbook potrebbe raccogliere un numero di ordine da un utente ed emetterlo tramite un parametro di output, oppure potrebbe utilizzare uno strumento per prenotare un volo ed emettere il numero di conferma tramite un parametro di output.

Crea esempi per controllare in che modo il playbook deve decidere il valore di ogni parametro di output. Ad esempio, se un parametro di output che rappresenta un numero di conferma deve derivare il suo valore dall'output di un utilizzo dello strumento, crea esempi in cui l'output dell'utilizzo dello strumento corrisponde al valore del parametro di output del playbook.

Passaggio dei parametri

Nota: un playbook di attività non può chiamare un playbook di routine, quindi lo scenario di passaggio dei parametri non è descritto di seguito.

A differenza dei flussi, i playbook non supportano l'inserimento di valori dei parametri con una sintassi specifica. Al contrario, i playbook si basano su istruzioni e esempi di prompt few-shot per determinare come devono essere utilizzati i valori dei parametri e come devono essere decisi quando si specificano i valori dei parametri.

Playbook di routine a flusso

Per passare i parametri da un playbook di routine a un flusso:

• Definisci i parametri di scrittura per il playbook di routine. Questi parametri diventeranno parametri di sessione.
• I flussi possono utilizzare i parametri di sessione.
• Includi l'utilizzo dei parametri nelle istruzioni e negli esempi.

Flusso a playbook di routine

Per passare i parametri da un flusso a un playbook di routine:

• I flussi scrivono i parametri di sessione.
• Definisci i parametri di lettura per il playbook di routine con gli stessi nomi.
• Includi l'utilizzo dei parametri nelle istruzioni e negli esempi.

Playbook di attività a flusso

Per passare i parametri da un playbook di attività a un flusso:

• Nelle impostazioni del flusso, definisci i parametri di input con gli stessi nomi.
• Includi l'utilizzo dei parametri nelle istruzioni e negli esempi.

Flusso a playbook di attività

Per passare i parametri da un flusso a un playbook di attività principale:

• Nelle impostazioni del flusso, definisci i parametri di restituzione.
• Includi l'utilizzo dei parametri nelle istruzioni e negli esempi.

Per passare i parametri da un flusso a un playbook di attività secondario:

• Definisci i parametri di input dell'attività che condividono lo stesso nome dei parametri di sessione nel flusso.
• Includi l'utilizzo dei parametri nelle istruzioni e negli esempi.

Playbook di routine a playbook di attività

Per passare i parametri da un playbook di routine a un playbook di attività:

• Definisci i parametri di input per il playbook di attività con gli stessi nomi.
• Includi l'utilizzo dei parametri nelle istruzioni e negli esempi.

Esempio che coinvolge gli strumenti

Considera un agente progettato per la vendita di biglietti per eventi con i seguenti playbook di attività:

1. Un playbook denominato Ticket ordering che effettua ordini utilizzando uno strumento denominato Ticket sales API.
   1. Questo playbook accetta un parametro di input di tipo number e nome event_id.
   2. Lo strumento Ticket sales API prevede una richiesta che include un event_id.
2. Un playbook denominato Event selection che aiuta gli utenti a selezionare un evento e poi li indirizza a Ticket ordering con il parametro event_id per acquistare i biglietti.

In questo esempio, per garantire che event_id venga passato in modo affidabile da Event selection a Ticket ordering e da Ticket ordering a Ticket sales API, sono necessari diversi esempi.

Il playbook Ticket ordering deve includere più esempi che:

• Hanno il parametro di input event_id specificato con un valore realistico, diverso in ogni esempio.
• Includono un'azione di utilizzo dello strumento con un corpo della richiesta che include lo stesso valore event_id realistico specificato nel parametro di input.

Il playbook Event selection deve includere più esempi che:

• Includono un'espressione dell'utente in cui l'utente seleziona un evento con un event_id realistico, diverso in ogni esempio.
• Includono una chiamata al playbook Ticket ordering che imposta il parametro event_id sullo stesso event_id realistico deciso dalla selezione dell'utente.

Oltre ad aggiungere esempi, prova ad aggiungere istruzioni specifiche alle istruzioni, all'obiettivoo ai dettagli dello strumento che spieghino come devono essere utilizzati i parametri. Ad esempio, il playbook Ticket ordering include la seguente istruzione:

- Use parameter event_id to send a buy_tickets request with ${TOOL: Ticket sales API}

Con gli esempi e le istruzioni descritti, il playbook Event selection decide correttamente un event_id in base alla selezione dell'utente e lo passa come parametro di input denominato event_id al Ticket ordering playbook. Poi, Ticket ordering passa lo stesso event_id nel corpo di una richiesta a Ticket sales API. I playbook si basano su esempi con valori dei parametri distinti per aiutarli a dedurre come devono essere utilizzati i parametri.