Playbook

Nota: la funzionalità Playbook è esclusa dall'accordo sul livello del servizio di Dialogflow CX SLA.

Un playbook è il componente di base degli agenti generativi. Un agente generativo in genere ha molti playbook, ognuno dei quali è definito per gestire attività specifiche. I dati del playbook vengono forniti all'LLM, in modo che disponga delle informazioni necessarie per rispondere alle domande ed eseguire le attività. Ogni playbook può fornire informazioni, inviare query a servizi esterni, o rimandare la gestione della conversazione a un flusso o a un altro playbook per gestire le sottoattività.

Limitazioni

Si applicano le seguenti limitazioni:

• Gli agenti che utilizzano i playbook non supportano l'invio di un SMS di accompagnamento della chiamata dalla route dell'intent di benvenuto predefinito nel flusso di avvio predefinito, ma puoi attivare l'opzione SMS di accompagnamento della chiamata nei flussi standard.
• I playbook non supportano l'input DTMF dai sistemi telefonici.

Supporto dei linguaggi

Consulta la colonna Playbook nel riferimento per il linguaggio. La qualità dei linguaggi contrassegnati per i playbook è stata testata con i modelli gemini-2.0-flash.

Quando utilizzi lingue diverse dall'inglese:

• Nella maggior parte dei casi, utilizza l'inglese per le istruzioni del playbook. Per alcune lingue e alcuni casi d'uso, potresti ottenere risposte leggermente migliori se fornisci anche le istruzioni nella lingua di destinazione.
• Dichiara il supporto linguistico nelle istruzioni del playbook. Ad esempio: "Rispondi sempre in francese".
• Definisci gli esempi nella lingua di destinazione.

Supporto del modello

Puoi selezionare il modello LLM utilizzato nel playbook nei seguenti punti:

• Seleziona il modello LLM a livello di agente.

  • Nella console Conversational Agents in Impostazioni agente -> AI generativa -> Playbook, seleziona il modello in base al nome visualizzato dal menu a discesa di tutti i modelli disponibili.
  • Specifica il nome del modello nel campo GenerativeSettings.llm_model_settings.model se utilizzi l'API per aggiornare l'impostazione dell'agente (vedi GenerativeSettings).

• Esegui l'override della selezione del modello a livello di richiesta.

  • Nel simulatore della console Conversational Agents, seleziona il modello in base al nome visualizzato dal menu a discesa quando testi un playbook.
  • Specifica il nome del modello nel campo DetectIntentRequest.query_params.llm_model_settings.model se stai testando l'agente tramite l'API (vedi DetectIntentRequest).

Nome modello	Specifica del modello	Fase di avvio
gemini-2.5-flash	Gemini 2.5 flash	GA
gemini-2.5-flash-lite	Gemini 2.5 flash lite	GA
gemini-2.0-flash-001	Gemini 2.0 flash	GA
gemini-2.0-flash-lite-001	Gemini 2.0 flash lite	GA

Supporto regionale

I playbook sono supportati nelle seguenti regioni:

• global
• asia-south1
• asia-southeast1
• asia-southeast2
• asia-northeast1
• australia-southeast1
• eu (multi-regione)
• europe-west1
• europe-west2
• europe-west3
• europe-west4
• europe-west6
• northamerica-northeast1
• us (multi-regione)
• us-central1
• us-east1
• us-west1

Dati del playbook

Un playbook è composto dai seguenti dati:

• Nome del playbook: un nome conciso in linguaggio naturale che aiuta gli sviluppatori e l'LLM a capire quali attività gestisce il playbook
• Obiettivi: descrizione di alto livello di ciò che il playbook deve raggiungere
• Istruzioni: definisce i passaggi della procedura da seguire per raggiungere l'obiettivo
• Esempi: conversazioni di esempio che sono esempi di prompt few-shot efficaci per l'LLM
• Parametri: vengono utilizzati per memorizzare informazioni su una conversazione, come input utente, informazioni di sistema dell'utente, risultati delle azioni, e così via.

Prompt LLM

Per ogni turno di conversazione, Dialogflow CX utilizza i dati del playbook in fase di progettazione e i dati della conversazione in fase di runtime per creare un prompt LLM entro i limiti dei token. I contenuti di questo prompt sono riassunti di seguito, dove le intestazioni sono illustrative e non necessariamente fanno parte del prompt.

# INTERNAL_SYSTEM_PROMPT
<you cannot see or edit this>

# INTERNAL_SYSTEM_EXAMPLES
<you cannot see or edit this>

# AVAILABLE_TOOLS_TO_CURRENT_PLAYBOOK
<tool names and schemas, for example...>

## Tool: my_datastore
   description: blah
   input: blah
   output: blah

## Tool: some_other_custom_tool
   description: blah
   input: blah
   output: blah

# PLAYBOOK
<verbatim Goal and Instructions that you provide in the console>

# PLAYBOOK_EXAMPLES
<as many Examples for the current Playbook as can fit in the prompt>

## Example 1

## Example 2
..
..
..
## Example N (up to the input token limit)

# CURRENT_CONVERSATION
<the conversation up to this point w/ some caveats...>

* Caveat 1: If there was a transition from Playbook A -> Playbook B, the
  Conversation that happened in Playbook A is summarized and provided as context
* Caveat 2: If there was a transition from Flow A -> Playbook A, the
  Conversation that happened prior to the entry of Playbook A is summarized and
  provided to the Playbook

Tipi di playbook

Quando crei un playbook, seleziona il tipo di playbook che vuoi: playbook di attività o playbook di routine.

Playbook di attività

I playbook di attività sono il tipo di playbook originale. Vengono utilizzati per suddividere le attività complesse in sottoattività più piccole e riutilizzabili. Vengono utilizzati per modellare le fasi di conversazione composizionali , in cui ogni fase comunica tramite parametri di input e output.

Di seguito è riportato un playbook di attività (chiamante) che chiama un altro playbook di attività (chiamato):

1. Il chiamante avvia il chiamato.
2. Il chiamante fornisce i parametri di input necessari al chiamato.
3. Il chiamato elabora queste informazioni, esegue la funzione designata e restituisce i parametri di output.
4. Il chiamante riceve i parametri dal chiamato.

Qualsiasi playbook di routine o di attività può chiamare un altro playbook di attività, ma un playbook di attività non può chiamare un altro playbook di routine.

Playbook di routine

I playbook di routine sono un nuovo tipo di playbook. Vengono utilizzati per modellare le fasi di conversazione sequenziali , in cui ogni fase è completa e indipendente. Possono chiamare i playbook di attività per scomporre le attività più grandi in sottoattività più piccole e possono passare ad altri playbook di routine o flussi.

Di seguito è riportato un playbook di routine (A) che passa a un altro playbook di routine (B) e poi a un flusso (C):

1. Il playbook di routine A può leggere i parametri della sessione all'avvio e scriverli poco prima di uscire.
2. Il playbook di routine A esce e passa al playbook di routine B.
3. Il playbook di routine B può leggere i parametri della sessione all'avvio e scriverli poco prima di uscire.
4. Il playbook di routine B esce e passa al flusso C.
5. Il flusso C può leggere e scrivere i parametri della sessione.

Se un playbook di routine non passa a un altro playbook di routine o flusso, la sessione tornerà all'ultimo flusso attivo o terminerà se non ne esiste uno.

I playbook di routine hanno il seguente comportamento di gestione dei parametri:

• Quando viene inserito un playbook di routine, ai relativi parametri di input vengono assegnati valori equivalenti ai parametri della sessione con lo stesso nome.
• Quando un playbook di routine esce, genera valori per i relativi parametri di output e li assegna ai parametri della sessione con lo stesso nome.

Confronta i tipi di playbook

Categoria	Playbook di attività	Playbook di routine
Latenza	Ogni volta che un playbook di attività chiama un altro playbook di attività, viene effettuata una chiamata LLM. Per una lunga catena di playbook di attività in un turno di conversazione, questo può aumentare la latenza.	Ogni playbook di routine in una serie di transizioni si verifica all'interno di un singolo turno di conversazione, quindi è presente una sola chiamata LLM e la latenza è migliorata.
Rigenerazione dei parametri	Quando un playbook di attività chiama un altro playbook di attività, i valori dei parametri devono essere rigenerati. Se esiste una lunga catena di playbook di attività, questa rigenerazione può comportare la perdita di contesto.	I playbook di routine utilizzano l'archiviazione della sessione per i parametri, il che crea un contesto più affidabile.
Integrazione dei parametri della sessione	I playbook di attività non interagiscono bene con i parametri della sessione e richiedono invece la definizione dei parametri di input e di ritorno.	I playbook di routine interagiscono bene con i parametri della sessione.
Riusabilità	Poiché ogni playbook di attività ha una relazione padre/figlio fissa, le attività sono strettamente accoppiate.	I playbook di routine possono essere definiti in modo indipendente l'uno dall'altro.

Playbook predefinito

Quando crei un agente generativo utilizzando la console Conversational Agents, viene creato automaticamente un playbook generativo predefinito.

Il playbook predefinito è il punto di partenza per le conversazioni, quindi presenta alcune importanti differenze rispetto ad altri playbook:

• Il playbook predefinito non riceve un riepilogo dei turni di conversazione precedenti.
• Il playbook predefinito non può definire o ricevere parametri di input.

Crea un playbook

Per creare un playbook:

1. Fai clic sull'icona del playbook nella navigazione a sinistra della console.
2. Fai clic sul pulsante Crea nuovo.
3. Seleziona il tipo di playbook Routine o Attività.
4. Fornisci i dati del playbook.

Utilizza la generazione AI per creare un playbook

Quando crei un playbook, si apre un riquadro AI generativa. Puoi utilizzarlo per generare i dati del playbook.

Importa ed esporta i playbook

Una volta creati i playbook utilizzando la console Conversational Agents, puoi esportarli per utilizzarli in un altro agente. Per esportare un playbook:

1. Vai all'elenco dei playbook.
2. Fai clic sul pulsante di esportazione del playbook che vuoi esportare.
3. Seleziona le opzioni di esportazione.
4. Fai clic su Esporta.

Per importare un playbook che hai esportato in precedenza:

1. Vai all'elenco dei playbook.
2. Fai clic su Importa.
3. Seleziona le opzioni di importazione.
4. Fai clic su Importa.