Playbook

Nota: la funzionalità Playbook è esclusa dallo SLA di Dialogflow CX.

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 per garantire 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 attività secondarie.

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 copioni non supportano l'input DTMF dai sistemi telefonici.

Supporto dei linguaggi

Consulta la colonna Playbook nel riferimento per il linguaggio. Le lingue contrassegnate per i playbooks sono state testate per la qualità con i modelli gemini-2.5-flash.

Quando utilizzi lingue diverse dall'inglese:

• Nella maggior parte dei casi, utilizza l'inglese per le istruzioni del playbook. Per alcune lingue e casi d'uso, puoi ottenere risposte leggermente migliori se fornisci anche 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 Agenti conversazionali Impostazione agente -> AI generativa -> Playbook, seleziona un modello in base al nome visualizzato dall'elenco dei modelli disponibili.
  • Specifica il nome del modello nel campo GenerativeSettings.llm_model_settings.model se utilizzi l'API per aggiornare le impostazioni dell'agente (vedi GenerativeSettings).

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

  • Nel simulatore della console Agenti conversazionali, seleziona un modello in base al nome visualizzato dall'elenco quando testi un playbook.
  • Specifica il nome del modello nel campo DetectIntentRequest.query_params.llm_model_settings.model se stai testando l'agente utilizzando 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-3.1-flash-lite	Gemini 3.1 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: una descrizione di alto livello di ciò che il playbook deve raggiungere.
• Istruzioni: i passaggi della procedura che l'agente deve seguire per raggiungere l'obiettivo.
• Esempi: conversazioni di esempio che sono esempi di prompt few-shot efficaci per l'LLM.
• Parametri: variabili che memorizzano informazioni su una conversazione, come l'input utente'utente, le informazioni di sistema dell'utente e i risultati dell'azione.

Prompt LLM

Per ogni turno conversazionale, 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 come segue, dove le intestazioni sono illustrative e non necessariamente 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, selezioni il tipo di playbook che vuoi: playbook di attività o playbook di routine.

Playbook delle attività

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

Un playbook di attività (chiamante) chiama un altro playbook di attività (destinatario):

1. Il chiamante avvia la chiamata.
2. Il chiamante fornisce al chiamato i parametri di input necessari.
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 della routine o di attività può chiamare un altro playbook di attività, ma un playbook di attività non può chiamare un altro playbook della routine.

Playbook delle routine

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

Di seguito è riportato un playbook di routine (A), la transizione a un altro playbook di routine (B) e la transizione a un flusso (C):

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

Se un playbook di routine non passa a un altro playbook di routine o flusso, la sessione torna all'ultimo flusso attivo o termina se non ce n'è 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 di sessione con lo stesso nome.
• Quando un playbook di routine viene chiuso, genera valori per i parametri di output e li assegna ai parametri di sessione con lo stesso nome.

Confrontare i tipi di playbook

Categoria	Playbook delle attività	Playbook della 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 delle attività in un turno di conversazione, questo può aumentare la latenza.	Ogni playbook della routine in una serie di transizioni si verifica all'interno di un singolo turno conversazionale, quindi c'è una sola chiamata LLM e una latenza migliorata.
Rigenerazione dei parametri	Quando un playbook delle attività chiama un altro playbook delle attività, i valori dei parametri devono essere rigenerati. Se esiste una lunga catena di playbook delle 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 sessione	I playbook delle attività non interagiscono bene con i parametri di sessione e richiedono invece la definizione di parametri di input e di ritorno.	L'interfaccia dei playbook delle routine funziona bene con i parametri di sessione.
Riusabilità	Poiché ogni playbook delle 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.

Guida pratica predefinita

Quando crei un agente generativo utilizzando la console Conversational Agents, Dialogflow crea automaticamente un playbook generativo predefinito.

Il playbook predefinito è il punto di partenza per le conversazioni, quindi presenta alcune importanti differenze rispetto agli 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. Seleziona l'icona del playbook nel menu di navigazione della console.
2. Fai clic su pulsante Crea.
3. Seleziona un tipo di playbook Routine o Attività.
4. Fornisci dati della guida pratica.

Utilizzare la generazione di AI per creare un playbook

Quando crei un playbook, si apre un riquadro di AI generativa. In questo modo puoi generare dati del playbook.

Importare ed esportare playbook

Dopo aver creato 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.