Alcuni prodotti e funzionalità sono in fase di rinominazione. Anche le funzionalità di playbook e flusso generativi sono in fase di migrazione a un'unica console consolidata. Consulta i dettagli.

Questa pagina è stata tradotta dall'API Cloud Translation.

Strumenti di playbook
Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

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

Puoi utilizzare gli strumenti integrati o crearne di personalizzati in base alle tue esigenze.

Test degli strumenti

Dopo aver creato uno strumento, puoi utilizzare la funzionalità di test dello strumento per verificare che funzioni. Quando visualizzi uno strumento, fai clic sul pulsante Prova sopra il riquadro degli strumenti. Si apre lo strumento per l'input nel simulatore. Fornisci l'input dello strumento, poi fai clic su Visualizza output per verificare l'output corretto dello strumento.

Puoi anche utilizzare la funzionalità di test dello strumento quando aggiungi uno strumento a un esempio.

Strumenti integrati

Gli strumenti integrati sono ospitati da Google. Puoi attivare questi strumenti negli agenti senza bisogno di 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 verrà fornito come valore del 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, 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 JSON.

Autenticazione API dello strumento OpenAPI

Quando chiami un'API esterna, sono supportate le seguenti opzioni di autenticazione:

Auth dell'agente di servizio Dialogflow
- Dialogflow può generare un token ID o un token di accesso utilizzando l'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 Google Cloud API dopo aver assegnato i ruoli richiesti a service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
Autenticazione dell'account di servizio
- Gli account di servizio possono essere utilizzati per autenticare le richieste di strumenti a qualsiasi API di Google che lo supporta. Poiché gli account di servizio sono entità, possono accedere alle risorse del progetto concedendo un ruolo, come faresti per qualsiasi altra entità. L'indirizzo email dell'account di servizio verrà utilizzato per generare un token di accesso che verrà inviato nell'intestazione Authorization della richiesta dello strumento.
- Per utilizzare questa funzionalità, sono richieste le seguenti autorizzazioni:
  - roles/iam.serviceAccountUser all'utente che crea o aggiorna lo strumento per utilizzare l'autenticazione dell'account di servizio.
  - roles/iam.serviceAccountTokenCreator all'agente di servizio Dialogflow.
- Se stai tentando di utilizzare gli account di servizio in più progetti, assicurati che i criteri dell'organizzazione lo supportino. Entrambe le autorizzazioni devono essere concesse nel progetto che contiene l'account di servizio.
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.
- Ti consigliamo di fornire la chiave API utilizzando Secret Manager.
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.
  - L'ID client, il client secret e l'endpoint del token del provider OAuth devono essere configurati in Dialogflow.
    - Ti consigliamo di fornire il segreto cliente utilizzando Secret Manager.
  - 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, come 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 con token bearer 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 Bearer per trasmettere dinamicamente il token Bearer dal client. Questo token è incluso nell'intestazione di autenticazione 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 sessione:
```
DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}
```
- Se devi configurare un token statico anziché recuperarlo da un parametro di sessione, ti consigliamo di fornire il token utilizzando Secret Manager.
Autenticazione TLS reciproca
- Consulta la documentazione sull'autenticazione TLS reciproca.
- I certificati client personalizzati sono supportati. Puoi configurare i certificati 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 il mutual TLS per tutti gli strumenti e gli webhook.
Certificato CA personalizzato
- Consulta la documentazione relativa ai certificati CA personalizzati.

Autenticazione di Secret Manager

Se utilizzi OAuth, chiave API o token di accesso, puoi archiviare le credenziali come secret utilizzando Secret Manager. Ecco i passaggi necessari per autenticare lo strumento utilizzando i secret:

Crea il tuo segreto se non ne hai già uno.
Concedi all'agente di servizio Dialogflow il ruolo Accesso ai secret di Secret Manager (roles/secretmanager.secretAccessor) per il nuovo secret.
Copia la credenziale negli appunti.
Aggiungi una nuova versione del secret al tuo secret. Incolla la credenziale come valore del secret.
- Ometti eventuali caratteri di nuova riga alla fine.
Copia il nome della versione del secret appena aggiunta. Il formato del nome è projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
Apri la schermata di modifica dello strumento, quindi:
- Se utilizzi OAuth, seleziona OAuth come Tipo di autenticazione, poi fai clic su Versione del segreto in Client secret e incolla il nome della versione del segreto nella casella di immissione Versione del segreto.
- Se utilizzi la chiave API, seleziona Chiave API come Tipo di autenticazione, quindi fai clic su Versione segreta in Chiave API. Incolla il nome della versione del secret nella casella di immissione Versione del secret.
- Se utilizzi il token bearer, seleziona Token bearer come Tipo di autenticazione, poi fai clic su Versione segreta in Token bearer. Incolla il nome della versione del secret nella casella di immissione Versione del secret.
Fai clic su Salva.

Accesso alla rete privata dello strumento OpenAPI

Lo strumento OpenAPI si integra con l'accesso alla rete privata di Service Directory, in modo da potersi connettere ai target API all'interno della rete VPC. In questo modo, il traffico rimane all'interno della rete Google Cloud e vengono applicati IAM e Controlli di servizio VPC.

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

Segui la configurazione della rete privata di Service Directory per configurare la rete VPC e l'endpoint di Service Directory.
Per il progetto dell'agente deve esistere l'account di servizio Agente di servizio Dialogflow con il seguente indirizzo:
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Concedi all'account di servizio Agente di servizio Dialogflow i seguenti ruoli IAM:
- servicedirectory.viewer del progetto Service Directory
- servicedirectory.pscAuthorizedService del progetto di rete
Fornisci il servizio Service Directory insieme allo schema OpenAPI e alle 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 alcuni casi, gli input potrebbero dover essere ricavati dai parametri della sessione raccolti durante un flusso o forniti come input del parametro di query insieme all'input utente.

Il parametro 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 non è disponibile un parametro di sessione di questo tipo, l'input generato dall'LLM verrà passato allo strumento.

Valori predefiniti dello strumento OpenAPI

Lo schema dell'API Open può essere utilizzato per specificare i valori predefiniti. I valori predefiniti vengono utilizzati solo se non è presente un valore di input generato da LLM o un valore di input basato sul parametro della sessione per quel parametro o quella proprietà.

I valori predefiniti possono essere specificati all'interno dello schema come segue:

     parameters:
       - in: query
         name: zipcode
         required: true
         description: Zip code to search for
         schema:
           type: integer
           default: 94043
     requestBody:
       content:
         application/json:
           schema:
             type: object
             properties:
               breed:
                 type: string
                 description: Bread of the pet.
               page_size:
                 type: integer
                 description: Number of pets to return.
                 default: 10

Se non è presente alcun valore generato da LLM, valore del parametro di sessione o valore predefinito, l'input non sarà specificato.

Strumenti per i datastore

Per informazioni sull'utilizzo degli strumenti di data store con un playbook, consulta la documentazione relativa agli strumenti di data store.

Strumenti per i connettori

Gli strumenti di connettore possono essere utilizzati da un agente per eseguire azioni utilizzando le tue connessioni configurate in Connettori di integrazione. Ogni strumento di connettore è configurato con una singola connessione e una o più azioni. Se necessario, è possibile creare più strumenti per una singola connessione per riunire diverse azioni da utilizzare dall'agente.

Lo strumento del connettore supporta i seguenti tipi di connettore:

Gli esempi devono essere utilizzati per migliorare l'utilizzo degli strumenti di connettore da parte dell'agente, dimostrando come l'agente debba chiamare lo strumento e utilizzare la risposta.

Crea una connessione

Per creare una connessione e collegarla all'agente, puoi andare a Strumenti > Crea, selezionare il tipo di strumento Connettore, il tipo di connettore scelto e utilizzare il pulsante Crea connessione. Verrà visualizzata la pagina per la creazione di Integration Connectors con una serie di campi precompilati.

In alternativa, puoi andare a Integration Connectors e seguire le istruzioni per creare una connessione.

Azioni del connettore

Per ogni strumento di connettore, esistono due tipi di azioni che possono essere messe a disposizione dell'agente (per ulteriori informazioni, consulta Entità, operazioni e azioni):

Operazioni CRUD sulle entità

Ognuna delle tue connessioni ha "entità" corrispondenti agli oggetti di quell'origine dati (per BigQuery si tratta di tabelle, per Salesforce si tratta di oggetti, come "Ordine" o "Richiesta").

Puoi eseguire operazioni CRUD su ogni entità:
- Crea: crea un'entità con valori di campo specificati
- Elenco: ricerca delle istanze di entità in base ai filtri
- Aggiorna: metodo basato su filtri per modificare i valori dei campi delle entità
- Elimina: elimina un'entità
- Get recupera una singola entità utilizzando entityId
Nota: l'operazione Get può essere utilizzata solo per recuperare un singolo record da un'entità con una chiave primaria. Spesso è più pratico utilizzare l'operazione List con una clauseFilter per recuperare un'entità.

Scopri di più sui dettagli delle operazioni CRUD delle entità nella documentazione dei connettori.
Azioni specifiche del connettore

Molti connettori supportano un'azione 'ExecuteCustomQuery' che consente di eseguire una query SQL sull'origine dati, dove ogni entità dell'origine dati può essere richiamata come tabella. Consulta questo elenco per i connettori supportati.

Le azioni aggiuntive variano in base al tipo di connettore. Ad esempio, consulta le azioni del connettore BigQuery o le azioni del connettore Salesforce.

Configurazione dei campi di input / output per le operazioni CRUD

Se selezioni campi di input o output specifici da utilizzare per l'azione dello strumento di connettore, puoi limitare la complessità di queste azioni per l'agente.

Ad esempio, se devi creare un'entità solo con un sottoinsieme dei relativi campi, la configurazione di questo insieme di campi nell'azione semplifica l'azione per l'agente.

La specifica di un insieme di campi di output riduce le dimensioni della risposta dello strumento (utile se i limiti di token sono un problema) e semplifica la gestione dell'output da parte dell'agente esponendo solo i campi pertinenti.

Autenticazione

Se la connessione in uso è configurata per consentire la sostituzione dell'autenticazione, lo strumento può essere configurato per trasmettere le credenziali da parametri di sessione specificati.

In qualità di autore dell'agente, sei responsabile di come vengono compilate queste credenziali nei parametri della sessione e lo strumento le trasmette automaticamente all'origine dati da utilizzare per l'autenticazione quando vengono chiamate le azioni dello strumento.

Strumenti di funzione

Se hai funzionalità accessibili dal codice client, ma non dagli strumenti OpenAPI, puoi utilizzare gli strumenti di funzione. Gli strumenti di funzione vengono sempre eseguiti sul lato client, non dall'agente.

La procedura è la seguente:

Il codice client invia una richiesta di rilevamento dell'intenzione.
L'agente rileva che è necessario uno strumento di funzione e la risposta al rilevamento dell'intenzione 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.
Il codice client chiama lo strumento.
Il codice client invia un'altra richiesta di rilevamento dell'intenzione 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 per il 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 di funzione, gli strumenti OpenAPI e di data store possono essere eseguiti lato client applicando una sostituzione dell'API quando interagisci con la sessione.

Ad esempio:

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