Strumenti del playbook

Con gli strumenti, puoi collegare i playbook a sistemi esterni. Questi sistemi possono aumentare la conoscenza dei playbook e consentire di eseguire attività complesse in modo efficiente.

Puoi usare gli strumenti integrati o creare strumenti personalizzati per soddisfare le tue esigenze.

Limitazioni

Si applicano le seguenti limitazioni:

  • Devi creare un datastore (o collegarne uno esistente) quando crei uno strumento di datastore per un agente.
  • App con entrambi datastore a blocchi e non a blocchi non sono supportati.

Strumenti integrati

Gli strumenti integrati sono ospitati da Google. Puoi attivare questi strumenti negli agenti senza bisogno di una configurazione manuale.

Gli strumenti integrati supportati sono:

  • Code Interpreter: uno strumento proprietario di Google che combina la capacità di generazione e di esecuzione del codice e consente all'utente di eseguire varie attività, tra cui analisi dei dati, visualizzazione dei dati, elaborazione di testi, risoluzione di equazioni o problemi di ottimizzazione.

L'agente è ottimizzato per determinare come e quando devono essere richiamati questi strumenti, ma puoi fornire esempi aggiuntivi in base ai tuoi casi d'uso.

Gli esempi devono avere uno schema come il seguente:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/df-code-interpreter-tool",
    "action": "generate_and_execute",
    "inputParameters": [
      {
        "name": "generate_and_execute input",
        "value": "4 + 4"
      }
    ],
    "outputParameters": [
      {
        "name": "generate_and_execute output",
        "value": {
          "output_files": [
            {
              "name": "",
              "contents": ""
            }
          ],
          "execution_result": "8",
          "execution_error": "",
          "generated_code": "GENERATED_CODE"
        }
      }
    ]
  }
}

Strumenti OpenAPI

Un agente può connettersi a un'API esterna utilizzando uno strumento OpenAPI fornendo lo schema OpenAPI. Per impostazione predefinita, l'agente chiamerà l'API per tuo conto. In alternativa, puoi eseguire gli strumenti OpenAPI sul lato client.

Schema di esempio:

openapi: 3.0.0
info:
  title: Simple Pets API
  version: 1.0.0
servers:
  - url: 'https://api.pet-service-example.com/v1'
paths:
  /pets/{petId}:
    get:
      summary: Return a pet by ID.
      operationId: getPet
      parameters:
        - in: path
          name: petId
          required: true
          description: Pet id
          schema:
            type: integer
      responses:
        200:
          description: OK
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      parameters:
        - name: petName
          in: query
          required: false
          description: Pet name
          schema:
            type: string
        - name: label
          in: query
          description: Pet label
          style: form
          explode: true
          required: false
          schema:
            type: array
            items:
              type: string
        - name: X-OWNER
          in: header
          description: Optional pet owner provided in the HTTP header
          required: false
          schema:
            type: string
        - name: X-SESSION
          in: header
          description: Dialogflow session id
          required: false
          schema:
            $ref: "@dialogflow/sessionId"
      responses:
        '200':
          description: An array of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
    post:
      summary: Create a new pet
      operationId: createPet
      requestBody:
        description: Pet to add to the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
      responses:
        '201':
          description: Pet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        owner:
          type: string
        label:
          type: array
          items:
            type: string

Facoltativamente, puoi utilizzare il riferimento allo schema interno @dialogflow/sessionId come tipo di schema del parametro. Con questo tipo di schema dei parametri, L'ID sessione Dialogflow per la conversazione corrente viene fornito come valore parametro. Ad esempio:

- name: X-SESSION
   in: header
   description: Dialogflow session id
   required: false
   schema:
     $ref: "@dialogflow/sessionId"

Limitazioni dello strumento OpenAPI

Si applicano le seguenti limitazioni:

  • I tipi di parametri supportati sono path, query, header. Il tipo di parametro cookie non è ancora supportato.
  • I parametri definiti dallo schema OpenAPI supportano i seguenti tipi di dati: string, number, integer, boolean e array. Il tipo object non è ancora supportato.
  • Al momento non puoi specificare i parametri di query nell'editor di esempi della console.
  • Il corpo della richiesta e della risposta deve essere vuoto o in formato JSON.

Autenticazione API dello strumento OpenAPI

Durante le chiamate sono supportate le seguenti opzioni di autenticazione un'API esterna:

  • Autorizzazione agente di servizio Dialogflow
    • Dialogflow può generare un token ID. o il token di accesso utilizzando Agente di servizio Dialogflow. Il token viene aggiunto nell'intestazione HTTP di autorizzazione quando Dialogflow chiama un'API esterna.
    • Un token ID può essere utilizzato per accedere alle funzioni e ai servizi Cloud Run dopo aver concesso i ruoli roles/cloudfunctions.invoker e roles/run.invoker a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Se le funzioni e i servizi Cloud Run si trovano nello stesso progetto di risorse, non è necessaria un'autorizzazione IAM aggiuntiva per richiamarli.
    • Un token di accesso può essere utilizzato per accedere ad altre API Google Cloud dopo aver concesso i ruoli richiesti service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
  • Chiave API
    • Puoi configurare l'autenticazione con chiave API fornendo il nome della chiave, la posizione della richiesta (intestazione o stringa di query) e la chiave API in modo che Dialogflow trasmetta la chiave API nella richiesta.

  • OAuth

    • Il flusso delle credenziali client OAuth è supportato per l'autenticazione server-to-server:

      • Questo flusso può essere utilizzato se la console di Agent Builder è il proprietario della risorsa e non è necessaria l'autorizzazione dell'utente finale.
      • Necessità di ID client, client secret e endpoint token del provider OAuth da configurare in Dialogflow.
      • Dialogflow scambia un token di accesso OAuth dal fornitore OAuth e lo passa nell'intestazione di autenticazione della richiesta.

    • Per altri flussi OAuth che richiedono l'autorizzazione dell'utente finale, ad esempio il flusso del codice di autorizzazione e il flusso PKCE:

      1. Dovrai implementare la tua UI di accesso e ottenere il token di accesso lato client.

      2. A questo punto puoi:

        a. Utilizza l'opzione di autenticazione Token di connessione per passare il token allo strumento OpenAPI. Dialogflow includerà questo token nell'intestazione di autorizzazione quando invoca lo strumento.

        b. Utilizza lo strumento Funzione per richiamare lo strumento sul lato client e passare il risultato della chiamata dello strumento a Dialogflow.

  • Token di connessione

    • Puoi configurare l'autenticazione di connessione per passare dinamicamente il token di connessione dal cliente. Questo token è incluso nell'intestazione auth della richiesta.
    • Quando configuri l'autenticazione dello strumento, puoi designare un parametro di sessione come token di accesso. Ad esempio, utilizza $session.params.<parameter-name-for-token> per specificare il token.
    • In fase di esecuzione, assegna il token Bearer al parametro session:
    DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}

  • Autenticazione TLS reciproca

    • Consulta Autenticazione TLS reciproca documentazione.
    • Sono supportati i certificati client personalizzati. Puoi configurare il client a livello di agente nella scheda Sicurezza delle impostazioni dell'agente. Il certificato (formato PEM) e la chiave privata (formato PEM) sono campi obbligatori. Una volta impostato, questo certificato client verrà utilizzato durante TLS reciproco per tutti gli strumenti e gli webhook.

  • Certificato CA personalizzato

Accesso alla rete privata dello strumento OpenAPI

Lo strumento OpenAPI si integra con l'accesso alla rete privata di Service Directory, pertanto può connettersi ai target API all'interno della rete VPC. In questo modo il traffico all'interno della rete Google Cloud applica in modo forzato IAM Controlli di servizio VPC.

Per configurare uno strumento OpenAPI che ha come target una rete privata:

  1. Segui Configurazione della rete privata di Service Directory per configurare la rete VPC e l'endpoint di Service Directory.

  2. L'agente di servizio Dialogflow account di servizio con il seguente indirizzo deve esistere per il tuo progetto agente: 

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
     Concedi all'account di servizio dell'agente di servizio Dialogflow i seguenti ruoli IAM:

    • servicedirectory.viewer del progetto Service Directory
    • servicedirectory.pscAuthorizedService del progetto di rete

  3. Fornire il servizio Service Directory insieme allo schema OpenAPI e informazioni di autenticazione facoltative durante la creazione dello strumento.

Accesso ai parametri di sessione dello strumento OpenAPI

Gli input dello strumento Open API derivano dalla conversazione degli utenti con l'LLM utilizzando lo schema come guida. In alcune situazioni, può essere necessario ricavare gli input Parametri di sessione raccolti durante un flusso o forniti come parametri di query insieme a input utente.

Il parametro di sessione che deve essere passato come input può essere specificato come

     parameters:
       - in: query
         name: petId
         required: true
         description: Pet id
         schema:
           type: integer
           x-agent-input-parameter: petId # Reads from the $session.params.petId
       - in: header
         name: X-other
         schema:
           type: string
           x-agent-input-parameter: $request.payload.header # Reads from the header specified in the request payload input
     requestBody:
       required: false
       content:
         application/json:
           schema:
             type: object
             properties:
               name:
                 type: string
                 x-agent-input-parameter: petName # Reads from the $session.params.petName
                 description: Name of the person to greet (optional).
               breed:
                 type: string
                 description: Bread of the pet.

Se questo parametro di sessione non è disponibile, l'input generato dall'LLM sarà passate allo strumento.

Strumenti per datastore

Gli strumenti dei datastore possono essere utilizzati da un agente per rispondere alle domande degli utenti finali provenienti dai tuoi datastore. Puoi configurare un datastore di ogni tipo per strumento, e lo strumento eseguirà una query su ciascuno di questi datastore per trovare le risposte. Per impostazione predefinita, l'agente chiamerà lo strumento per il datastore per tuo conto. In alternativa, puoi eseguire strumenti per datastore sul lato client.

Il tipo di magazzino dati può essere uno dei seguenti:

  • PUBLIC_WEB: un datastore con contenuti web pubblici.
  • UNSTRUCTURED: un datastore contenente dati privati non strutturati.
  • STRUCTURED: un data store contenente dati strutturati (ad es. domande frequenti).

L'esempio seguente mostra come fare riferimento a un archivio dati:

"dataStoreConnections": [
  {
    "dataStoreType": "PUBLIC_WEB",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "UNSTRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "STRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  }
]

Le risposte dello strumento del datastore possono contenere anche snippet sull'origine dei contenuti che è stata utilizzata per generare la risposta. L'agente può fornire ulteriori istruzioni su come procedere con la risposta dai datastore o come rispondere in assenza di risposta.

Puoi sovrascrivere una risposta aggiungendo un'opzione Voce delle domande frequenti per una domanda specifica.

Gli esempi possono essere utilizzati per migliorare ulteriormente il comportamento dell'agente. L'esempio dovrebbe avere i seguenti schemi:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
    "action": "TOOL_DISPLAY_NAME",
    "inputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME input",
        "value": {
          "query": "QUERY"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME output",
        "value": {
          "answer": "ANSWER",
          "snippets": [
            {
              "title": "TITLE",
              "text": "TEXT_FROM_DATASTORE",
              "uri": "URI_OF_DATASTORE"
            }
          ]
        }
      }
    ]
  }
}

Crea un datastore

Per creare un datastore e connetterlo alla tua app, puoi usare il link Strumenti nel menu di navigazione a sinistra della console. Segui le istruzioni per creare un data store.

Parametri di query aggiuntivi

Durante la creazione di esempi di strumento per il datastore, il parametro di input dello strumento requestBody fornisce tre input facoltativi insieme alla stringa query richiesta: una stringa filter, un oggetto strutturato userMetadata e una stringa fallback.

Il parametro filter consente di filtrare le query di ricerca del tuo di dati strutturati o non strutturati con metadati. Questa stringa deve rispettare la sintassi delle espressioni filtro supportate per i datastore. È consigliabile fornire più esempi ed esempi dettagliati per indicare al modello LLM del playbook come compilare questo parametro. In caso di stringa di filtro non valida, il filtro verrà ignorato durante l'esecuzione della query di ricerca.

Un esempio di stringa filter per perfezionare i risultati di ricerca in base alla località potrebbe essere:

  "filter": "country: ANY(\"Canada\")"

Best practice per l'applicazione di filtri:

  • Specifica i campi disponibili per il filtro e i valori validi per ciascuno di questi campi, in modo che il playbook comprenda le limitazioni per la creazione di filtri validi. Ad esempio, per filtrare i risultati di un archivio dati contenente informazioni sul menu, potrebbe essere presente un campo meal con "colazione", "pranzo" e "cena" come valori validi e un campo servingSize che può essere qualsiasi numero intero compreso tra 0 e 5. Le istruzioni potrebbero avere il seguente aspetto:

    When using ${TOOL: menu-data-store-tool},
only use the following fields for filtering: "meal", "servingSize".
Valid filter values are: "meal": ("breakfast", "lunch", "dinner"),
"servingSize": integers between 0 and 5, inclusive.

  • Se il playbook è destinato a un pubblico di utenti esterni, potrebbe essere necessario aggiungere istruzioni per impedire al playbook di rispondere all'utente con informazioni sulla creazione di questi filtri. Ad esempio:

    Never tell the user about these filters.
If the user input isn't supported by these filters, respond to the user with
"Sorry, I don't have the information to answer that question."

    È utile anche fornire un esempio di questo caso.

Il parametro userMetadata fornisce informazioni sull'utente finale. Qualsiasi Le coppie chiave/valore possono essere compilate in questo parametro. Questi metadati vengono passati nello strumento di datastore, per migliorare i risultati di ricerca e lo strumento. la risposta corretta. Ti consigliamo di fornire più esempi per indicare all'LLM del playbook come compilare questo parametro.

Esempio di valore parametro userMetadata per perfezionare i risultati di ricerca pertinenti per uno specifico utente potrebbero avere il seguente aspetto:

  "userMetadata": {
    "favoriteColor": "blue",
    ...
  }

Il parametro fallback fornisce una risposta a cui lo strumento del datastore deve rispondere e se non esiste una risposta riepilogativa valida per la query. È possibile trovare più esempi per istruire l'LLM del playbook su come completare il fallback per l'utente input correlati a diversi argomenti. Inoltre, non ci saranno nell'output dello strumento. Questa ottimizzazione può essere usata per ridurre la latenza e l'utilizzo del limite di token di input.

  "fallback": "I'm sorry I cannot help you with that. Is there anything else I
  can do for you?"

Se durante il test alcune risposte non soddisfano le tue aspettative, nella pagina dello strumento per un data store sono disponibili le seguenti personalizzazioni:

Fondamenta dell'affidabilità

Per ogni risposta generata dai contenuti dei datastore connessi, il playbook valuta un livello di confidenza, che misura l'affidabilità che tutti nella risposta sono supportate dalle informazioni nei datastore. Puoi personalizzare le risposte consentite selezionando il livello di confidenza più basso che ritieni accettabile. Solo risposte uguali o superiori a questo il livello di confidenza.

Puoi scegliere tra 5 livelli di confidenza: VERY_LOW, LOW, MEDIUM, HIGH e VERY_HIGH.

Configurazione del riassunto

Puoi selezionare il modello generativo utilizzato da un gestore del datastore per richiesta di riassunto generativo. Se non viene selezionato nessuno, viene utilizzata un'opzione di modello predefinita. La tabella seguente contiene le opzioni disponibili:

Identificatore modello Supporto delle lingue
text-bison@002 Disponibile in tutte le lingue supportate.
gemini-1.0-pro-001 Disponibile in tutte le lingue supportate.

Puoi anche fornire il tuo prompt per la chiamata LLM di sintesi.

Il prompt è un modello di testo che può contenere segnaposto predefiniti. I segnaposto verranno sostituiti con i valori appropriati in fase di esecuzione e il testo finale verrà inviato all'LLM.

I segnaposto sono i seguenti:

  • $original-query: il testo della query dell'utente.
  • $rewritten-query: il playbook utilizza un modulo di riscrittura per riscrivere la query originale dell'utente in un formato più preciso.

  • $sources: il playbook utilizza Enterprise Search per cercare le fonti in base alla query dell'utente. Le origini trovate vengono visualizzate in un formato specifico:

    [1] title of first source
content of first source
[2] title of second source
content of first source

  • $end-user-metadata: le informazioni sull'utente che invia la query vengono visualizzate nel seguente formato:

    The following additional information is available about the human: {
  "key1": "value1",
  "key2": "value2",
  ...
}

  • $conversation: la cronologia delle conversazioni viene visualizzata nel seguente formato:

    Human: user's first query
AI: answer to user's first query
Human: user's second query
AI: answer to user's second query

Un prompt personalizzato deve indicare all'LLM di restituire "NOT_ENOUGH_INFORMATION" quando non può fornire una risposta. Il playbook trasformerà questa costante in un messaggio intuitivo per l'utente.

Impostazioni del payload

Le impostazioni del payload consentono di aggiungere gli snippet dell'archivio dati come contenuti avanzati nel payload della risposta visualizzato nel messenger.

Frasi escluse (configurazione a livello di playbook)

Hai la possibilità di definire frasi specifiche che non devono essere consentite. Questi vengono configurati a livello di playbook e utilizzati da entrambi gli LLM e gli strumenti per i datastore. Se la risposta generata o parti del prompt LLM, come gli input dell'utente, contengono una delle frasi vietate, la risposta non verrà mostrata.

Strumenti di funzione

Se hai a disposizione funzionalità accessibili tramite il codice cliente, ma non sono accessibili dagli strumenti OpenAPI, puoi usare gli strumenti per le funzioni. Gli strumenti per le funzioni vengono sempre eseguiti sul lato client, e non dall'agente.

La procedura è la seguente:

  1. Il codice client invia una richiesta di rilevamento di intent.
  2. L'agente rileva che è necessario uno strumento per le funzioni, e la risposta di rilevamento dell'intento contiene il nome dello strumento insieme agli argomenti di input. Questa sessione viene messa in pausa fino a quando non viene ricevuta un'altra richiesta di rilevamento dell'intenzione con il risultato dello strumento.
  3. Il codice client chiama lo strumento.
  4. Il codice client invia un'altra richiesta di rilevamento di intent che fornisce il risultato dello strumento come argomenti di output.

L'esempio seguente mostra lo schema di input e output di uno strumento di funzione:

{
  "type": "object",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, for example, San Francisco, CA"
    }
  },
  "required": [
    "location"
  ]
}

{
  "type": "object",
  "properties": {
    "temperature": {
      "type": "number",
      "description": "The temperature"
    }
  }
}

L'esempio seguente mostra la richiesta e la risposta iniziali di rilevamento dell'intenzione utilizzando REST:

HTTP method and URL:
POST https://REGION_ID-dialogflow.googleapis.com/v3/projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/sessions/SESSION_ID:detectIntent
{
  "queryInput": {
    "text": {
      "text": "what is the weather in Mountain View"
    },
    "languageCode": "en"
  }
}

{
  "queryResult": {
    "text": "what is the weather in Mountain View",
    "languageCode": "en",
    "responseMessages": [
      {
        "source": "VIRTUAL_AGENT",
        "toolCall": {
          "tool": "<tool-resource-name>",
          "action": "get-weather-tool",
          "inputParameters": {
            "location": "Mountain View"
          }
        }
      }
    ]
  }
}

L'esempio seguente mostra la seconda richiesta di rilevamento dell'intenzione, che fornisce il risultato dello strumento:

{
  "queryInput": {
    "toolCallResult": {
      "tool": "<tool-resource-name>",
      "action": "get-weather-tool",
      "outputParameters": {
        "temperature": 28.0
      }
    },
    "languageCode": "en"
  }
}

Esecuzione lato client

Come gli strumenti per le funzioni, OpenAPI e gli strumenti per datastore possono essere eseguite sul lato client applicando un override dell'API durante l'interazione con la sessione.

Ad esempio:

DetectIntentRequest {
  ...
  query_params {
    playbook_state_override {
      playbook_execution_mode: ALWAYS_CLIENT_EXECUTION
    }
  }
  ...
}

La procedura è la seguente:

  1. Il codice cliente invia una richiesta di rilevamento di intent che specifica l'esecuzione del client.
  2. L'agente rileva che è necessario uno strumento e la risposta al rilevamento dell'intento contiene il nome dello strumento insieme agli argomenti di input. Questa sessione viene messa in pausa fino a quando non viene ricevuta un'altra richiesta di rilevamento dell'intenzione con il risultato dello strumento.
  3. Il codice client chiama lo strumento.
  4. Il codice client invia un'altra richiesta di rilevamento dell'intenzione che fornisce il risultato dello strumento come argomenti di output.