Esempi di playbook

Nota: la console di Vertex AI Agent Builder continua a fare riferimento ai playbook come agenti. A breve, nella console, verrà aggiornato a playbook.

Ogni playbook deve avere uno o più esempi. Questi esempi sono conversazioni di esempio tra un utente finale e il playbook, inclusi il dialogo e le azioni eseguite dall'agente. Si tratta di esempi di prompt few-shot per l'LLM.

La console fornisce un'interfaccia per inserire le azioni.

Agenti multilingue

Se vuoi che il tuo agente gestisca più lingue, gli esempi devono utilizzare ciascuna delle lingue.

Riepilogo dell'input e dell'output di esempio

Oltre ai parametri di input e output, i playbook supportano la ricezione di un riepilogo dell'input e l'emissione di un riepilogo dell'output per lo scambio di informazioni con altri playbook. I riepiloghi sono utili per trasmettere informazioni contestuali astratte tra i playbook, mentre i parametri sono più utili per trasmettere campi strutturati e ben definiti tra i playbook. I parametri sono l'unico modo per scambiare dati tra flussi e playbook.

Aggiungi riepiloghi dell'input pertinenti agli esempi per condizionare il playbook in modo che adatti le sue azioni in base ai riepiloghi dell'input in fase di runtime. Aggiungi riepiloghi dell'output che includano dettagli pertinenti e accurati sulla conversazione di esempio per mostrare al playbook quali dettagli sono importanti da riassumere.

Nota: gli esempi per il playbook predefinito potrebbero non definire parametri di input o un riepilogo dell'input. Il playbook predefinito funge da punto di ingresso per le conversazioni degli utenti, quindi non ha modo di ricevere parametri di input.

Stato di esempio

In un determinato punto della conversazione, un playbook si troverà in uno dei seguenti stati:

• OK: il playbook ha raggiunto correttamente il suo obiettivo e il controllo verrà ora trasferito al playbook principale.
• CANCELLED: l'utente ha deciso di non procedere con l'obiettivo assegnato al playbook. Il controllo verrà ora trasferito al playbook principale. Se il playbook principale è un flusso CX, l'intent dell'input dell'utente verrà rilevato prima dell'esecuzione del flusso.
• FAILED: il playbook non può procedere con l'obiettivo a causa di un errore (ad es. lo strumento restituisce l'errore 500). La sessione terminerà con lo stato di errore. Alla risposta verrà aggiunto un messaggio EndInteraction.
• ESCALATED: il playbook ha deciso di non poter raggiungere l'obiettivo e deve segnalare la situazione a una persona. La sessione terminerà con lo stato di escalation. Alla risposta verrà aggiunto un messaggio EndInteraction.
• PENDING: la conversazione continua all'interno del playbook.

L'esempio di primo livello e le relative invocazioni del playbook devono essere contrassegnati con uno stato corrispondente al playbook a cui fanno riferimento.

Strategia di selezione

L'impostazione della strategia di selezione controlla se un esempio è incluso nel prompt del playbook inviato all'LLM. Sono disponibili le seguenti opzioni:

• Seleziona dinamicamente: l'esempio viene incluso in modo condizionale, in base alla sua pertinenza per il contesto della conversazione corrente. L'esempio potrebbe essere omesso se il prompt si avvicina al limite di token.

• Seleziona sempre: l'esempio viene sempre incluso, indipendentemente dal contesto della conversazione. L'esempio potrebbe essere omesso se il prompt si avvicina al limite di token.

• Non selezionare mai: l'esempio non viene mai incluso nel prompt. L'esempio non avrà alcun effetto sul rendimento del playbook. Questa impostazione è utile per escludere temporaneamente un esempio per i test.

Aggiungi azione

Un esempio fornito all'interno di un playbook è costituito da una serie di azioni. Queste azioni possono variare nelle loro combinazioni, ma descrivono principalmente l'interazione tra l'utente e il playbook, insieme alle azioni intraprese nel frattempo per soddisfare la query o i requisiti dell'utente.

Esistono due modi per aggiungere azioni a un esempio:

• Per aggiungere un'azione manualmente, fai clic sul pulsante + nella parte inferiore del riquadro a destra o sul pulsante Aggiungi azione quando tieni il puntatore sopra le azioni esistenti. Puoi utilizzare queste opzioni quando crei un nuovo esempio facendo clic sull'opzione + Esempio o quando modifichi un esempio esistente.
• Per generare automaticamente le azioni in base alle istruzioni del playbook esistente, inserisci un input utente nel campo Inserisci input utente nella parte inferiore del riquadro a destra. Puoi utilizzare questa opzione quando crei o modifichi un esempio. In alternativa, puoi utilizzare questa opzione quando testi il playbook in fase di runtime nel riquadro Anteprima playbook a destra. Per salvare le azioni in un esempio dal riquadro Anteprima playbook , fai clic su Salva esempio dopo aver selezionato l'invocazione del playbook dall'elenco di invocazioni a sinistra del riquadro Anteprima playbook.

Assicurati di controllare la correttezza delle azioni generate automaticamente e di modificarle, se necessario. Ciò è particolarmente importante per i playbook con pochi o nessun esempio.

I seguenti tipi di azioni sono supportati dal playbook:

Risposta del playbook

La risposta del playbook alla query dell'utente.

Input utente

La query dell'utente.

Utilizzo dello strumento

Si tratta di un invocazione dello strumento per ottenere ulteriori informazioni necessarie per soddisfare la query dell'utente. Questa azione deve specificare i seguenti dettagli:

• Strumento: nome dello strumento da invocare.

• Azione: nome dell'operazione per lo strumento OpenAPI da invocare. Per gli strumenti del datastore e gli strumenti delle funzioni, il nome dell'azione è uguale al nome dello strumento.

• Input dello strumento: input da includere nella chiamata allo strumento. Questi input vengono in genere derivati dai turni di conversazione precedenti con l'utente.

  Per gli strumenti Open API, requestBody è necessario il JSON per POST, PUT e PATCH tipi di metodi.

  Esempio di input requestBody `requestBody` dello strumento Open API per l'azione createPet:

  {
    "id": 1,
    "name": "Luna"
  }
  

  Per lo strumento del datastore, l'esempio di requestBody in cui la query è obbligatoria e gli altri campi sono facoltativi.

  {
    "query": "Where is my nearest store?",
    "filter": "country: ANY(\"United States\")",
    "userMetadata": {
      "userCity": "San Francisco",
    },
    "fallback": "We don't have any stores in your area."
  }
  

• Output dello strumento: la risposta dell'invocazione dello strumento. Si tratta di una risposta JSON valida dello strumento all'input specificato. Per gli strumenti Open API, può anche essere una stringa di errore (ad esempio, "404 Not found").

  Esempio di output dello strumento Open API per l'azione listPets:

  {
    "pets": [
      {
        "id": 1,
        "name": "Luna"
      },
      {
        "id": 2,
        "name": "Charlie"
      }]
  }
  

  Esempio di output dello strumento del datastore:

  {
    "answer": "Here's the address to your nearest store ...",
    "snippets": [
      {
        "title": "San Francisco Downtown",
        "uri": "https://www.example.com/San_Francisco_Downtown",
        "text": "Address for San Francisco Downtown .."
      }
    ]
  }
  

Per garantire che il playbook sia a prova di errore, includi anche esempi di come il playbook deve rispondere quando l'invocazione dello strumento non riesce. L'errore di invocazione dello strumento Open API può essere rappresentato come una stringa di errore ("404 not found") nell'output dello strumento. Per gli strumenti del datastore l'input fallback può essere utilizzato per specificare come rispondere se non è presente una risposta riassuntiva.

Se vuoi che il tuo strumento del datastore includa l'URI nella risposta del playbook, aggiungi esempi che contengano l'URI con cui vuoi che il playbook risponda. Se questo URI proviene dallo strumento del datastore, l'output dello strumento del datastore deve contenere un URI che corrisponda all'URI nella risposta del playbook. Tieni presente che fallback non può essere utilizzato in questo scenario perché disattiverà la funzionalità del playbook LLM di riformulare la risposta dello strumento del datastore per includere gli URI nella risposta del playbook.

Gli esempi contenenti azioni di utilizzo dello strumento possono diventare piuttosto dettagliati e contribuire a un aumento del consumo del limite di token di input. Per garantire un utilizzo efficiente dei token, assicurati che gli output degli strumenti siano concisi e contengano informazioni pertinenti agli obiettivi del playbook. Per gli strumenti del datastore, valuta la possibilità di rimuovere gli snippet dagli esempi, in quanto possono contribuire a un elevato consumo di token di input.

Invocazione del playbook

Questa azione viene utilizzata quando il playbook deve invocare un altro playbook di attività per soddisfare la query dell'utente. Questa azione deve specificare i seguenti dettagli:

• Playbook: nome del playbook da invocare.
• Riepilogo dell'input dell'invocazione del playbook: Un riepilogo delle parti pertinenti della conversazione precedente utile per il playbook da invocare.
• Parametri di input: Parametri di input da passare al playbook.
• Riepilogo dell'output dell'invocazione del playbook: Un riepilogo di ciò che il playbook deve generare al completamento del suo obiettivo.
• Parametri di output: Parametri di output generati dal playbook al completamento del suo obiettivo.

Transizione del playbook

Un'azione di transizione del playbook è un'azione terminale (non deve essere seguita da altre azioni) che indica che il playbook di routine ha deciso di uscire e passare a un playbook di routine di destinazione. Tieni presente che, poiché questa azione indica che il playbook esce, aggiungi i parametri di output del playbook all'output del playbook dell'esempio.

Invocazione del flusso

Questa azione viene utilizzata quando il playbook di attività deve invocare un flusso. Questa azione deve specificare i seguenti dettagli:

• Flusso: nome del flusso da invocare.
• Parametri di input del flusso: Parametri di input da passare al flusso.
• Parametri di ritorno del flusso: Parametri di output restituiti dal flusso.

Transizione del flusso

Un'azione di transizione del flusso è un'azione terminale (non deve essere seguita da altre azioni) che indica che il playbook di routine ha deciso di uscire e passare a un flusso di destinazione. Tieni presente che, poiché questa azione indica che il playbook esce, aggiungi i parametri di output del playbook all'output del playbook dell'esempio.