Playbook

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

Un playbook è l'elemento 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 abbia le 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 Call Companion dal percorso dell'intent di benvenuto predefinito nel flusso di avvio predefinito, ma puoi attivare l'opzione SMS di Call Companion nei flussi standard.
• I playbook non supportano l'input DTMF dai sistemi telefonici.

Supporto dei linguaggi

Consulta la colonna Playbook nel riferimento per le lingue. Le lingue contrassegnate per i playbook sono state testate per verificarne 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 le lingue supportate nelle istruzioni del playbook, ad esempio: "Rispondi sempre utilizzando la lingua francese".
• Definisci gli esempi nella lingua di destinazione.

Supporto del modello

Puoi selezionare il modello LLM utilizzato nel playbook nelle seguenti posizioni:

• Seleziona il modello LLM a livello di agente.

  • Nella console di Conversational Agents, vai a Impostazioni agente -> AI generativa -> Playbook e 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 (consulta GenerativeSettings).

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

  • Nel simulatore della console Conversational Agents, seleziona un modello in base al nome visualizzato nell'elenco durante il test di 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	Model Spec	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
gemini-3.5-flash-lite	Gemini 3.5 Flash Lite	GA

Supporto regionale

I playbook sono supportati nelle seguenti regioni:

• global
• asia-south1
• asia-southeast1
• asia-southeast2
• asia-northeast1
• australia-southeast1
• eu (multiregionale)
• europe-west1
• europe-west2
• europe-west3
• europe-west4
• europe-west6
• northamerica-northeast1
• us (multiregionale)
• 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 realizzare.
• Istruzioni: i passaggi del processo che l'agente deve seguire per raggiungere l'obiettivo.
• Esempi: conversazioni di esempio che sono effettivamente esempi di prompt few-shot per l'LLM.
• Parametri: variabili che memorizzano informazioni su una conversazione, ad esempio l'input utente'utente, le informazioni sul sistema dell'utente e i risultati delle azioni.

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 di token. I contenuti di questo prompt sono riassunti di seguito, dove le intestazioni sono da intendersi come 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 delle attività o playbook della routine.

Playbook delle attività

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

Un playbook di attività (chiamante) 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. La funzione chiamata 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 dell'attività può chiamare un altro playbook dell'attività, ma un playbook dell'attività non può chiamare un altro playbook della routine.

Playbook della routine

I playbook delle 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 delle attività per scomporre le attività più grandi in attività secondarie più piccole e possono passare ad altri playbook della routine o flussi.

Di seguito è riportato un playbook della routine (A) che passa a un altro playbook della routine (B), che passa 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 termina e passa al playbook della routine B.
3. Il playbook della routine B può leggere i parametri di sessione all'avvio e scrivere i parametri di sessione appena prima di uscire.
4. Il playbook della routine B termina e passa al flusso C.
5. Il flusso C può leggere e scrivere i parametri di sessione.

Se un playbook della routine non passa a un altro playbook della routine o a un altro flusso, la sessione torna all'ultimo flusso attivo o termina se non ce n'è uno.

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

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

Confronta i tipi di playbook

Categoria	Playbook delle attività	Playbook della routine
Latenza	Ogni volta che un playbook delle attività chiama un altro playbook delle 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 della routine in una serie di transizioni si verifica all'interno di un singolo turno di conversazione, quindi esiste una sola chiamata LLM e una 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 delle attività, questa rigenerazione può portare alla perdita di contesto.	I playbook della routine utilizzano lo spazio di archiviazione della sessione per i parametri, creando un contesto più affidabile.
Integrazione dei parametri di 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.	I playbook delle routine si interfacciano bene con i parametri di sessione.
Riusabilità	Poiché ogni playbook delle attività ha una relazione padre/figlio fissa, le attività presentano un alto accoppiamento.	I playbook della routine possono essere definiti indipendentemente l'uno dall'altro.

Playbook predefinito

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

Il playbook predefinito è il punto di partenza delle conversazioni, quindi presenta alcune differenze importanti 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 i dati del playbook.

Utilizza la generazione AI per creare un playbook

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

Importa ed esporta playbook

Dopo aver creato i playbook utilizzando la console di 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 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.