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

Utilizzando gli strumenti, puoi connettere 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 strumenti integrati o creare strumenti personalizzati in base alle tue esigenze.

Test dello strumento

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

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

Strumenti integrati

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

Gli strumenti integrati supportati sono:

Code Interpreter: uno strumento proprietario di Google che combina la funzionalità di generazione ed esecuzione del codice e consente all'utente di svolgere varie attività, tra cui: analisi dei dati, visualizzazione dei dati, elaborazione del testo, 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 per adattarli ai tuoi casi d'uso.

Gli esempi devono avere uno schema simile al 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.

Puoi verificare che lo strumento sia configurato correttamente utilizzando la funzionalità Test dello strumento disponibile nella pagina dello strumento. Questa funzionalità è disponibile anche nella visualizzazione di esempio quando aggiungi una chiamata allo strumento all'esempio.

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

Se vuoi, puoi utilizzare il riferimento allo schema interno @dialogflow/sessionId come tipo di schema dei parametri. Con questo tipo di schema di parametri, l'ID sessione Dialogflow per la conversazione corrente verrà fornito comvalore parametroro. 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 e 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 parametri di ricerca nell'editor di esempi della console.
Il corpo della richiesta e della risposta deve essere vuoto o in formato JSON.

Generazione dello schema dello strumento OpenAPI

Quando fornisci uno schema, puoi utilizzare il pulsante Usa Gemini per utilizzare l'AI generativa per creare lo schema. Per guidare la generazione, puoi fornire quanto segue:

Un URL di richiesta
Un metodo HTTP (GET, POST e così via)
Input di esempio
Esempio di output
Un prompt di testo che descrive lo strumento

Una volta generato, puoi modificarlo in base alle esigenze e aggiungere manualmente altri URL e metodi.

Autenticazione API dello strumento OpenAPI

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

Autenticazione dell'agente di servizio Dialogflow

Dialogflow può generare un token ID 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 Cloud Run 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 Cloud Run e i servizi Cloud Run si trovano nello stesso progetto di risorse, non hai bisogno di un'autorizzazione IAM aggiuntiva per chiamarli.

Autenticazione del service account

I service account possono essere utilizzati per autenticare le richieste di strumenti a qualsiasi API di Google che lo supporti.

Se non l'hai ancora fatto, crea un account di servizio.

Poiché i service account sono entità, possono accedere alle risorse del tuo progetto concedendo loro un ruolo, proprio come faresti per qualsiasi altra entità. L'email dell'account di servizio verrà utilizzata per generare un token di accesso che verrà inviato nell'intestazione Authorization della richiesta dello strumento.

L'utente che configura lo strumento per utilizzare i service account deve disporre delle seguenti autorizzazioni:

roles/iam.serviceAccountUser

Affinché Conversational Agents (Dialogflow CX) generi token, l'agente di servizio Dialogflow deve disporre delle seguenti autorizzazioni:

roles/iam.serviceAccountTokenCreator

Il account di servizio deve disporre anche delle autorizzazioni per accedere al servizio che ospita lo strumento.

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 la trasmetta nella richiesta.
Ti consigliamo di fornire la chiave API utilizzando Secret Manager. Dopo il 15 agosto 2025, gli agenti esportati non conterranno più chiavi API con valori non elaborati.

OAuth

Il flusso delle credenziali client OAuth è supportato per l'autenticazione server-to-server:
- Questo flusso può essere utilizzato se la console AI Applications è il proprietario della risorsa e non è necessaria l'autorizzazione dell'utente finale.
- L'ID client, il client secret e l'endpoint token del provider OAuth devono essere configurati in Dialogflow.
  - Ti consigliamo di fornire il client secret utilizzando Secret Manager. Dopo il 15 agosto 2025, gli agenti esportati non conterranno più i client secret con valori non elaborati.
- Dialogflow scambia un token di accesso OAuth dal provider OAuth e lo trasmette 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 di autenticazione per passare il token allo strumento OpenAPI. Dialogflow includerà questo token nell'intestazione di autorizzazione quando richiama lo strumento.
  
  b. Utilizza lo strumento Funzione per richiamare lo strumento autonomamente sul lato client e passare il risultato della chiamata allo 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 che funga da token Bearer. Ad esempio, utilizza $session.params.<parameter-name-for-token> per specificare il token.

In fase di runtime, 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. Dopo il 15 agosto 2025, gli agenti esportati non conterranno più token Bearer con valori non elaborati.

Autenticazione TLS reciproca

Consulta la documentazione relativa all'autenticazione TLS reciproca.
Sono supportati i certificati client personalizzati. 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 mutual TLS per tutti gli strumenti e i webhook.

Certificato CA personalizzato

Consulta la documentazione relativa ai certificati CA personalizzati.

Autenticazione Secret Manager

Se utilizzi OAuth, la chiave API o il token Bearer, 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 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) sul nuovo secret.
Copia le credenziali negli appunti.
Aggiungi una nuova versione del secret al tuo secret. Incolla la credenziale come valore del secret.
- Ometti qualsiasi carattere di nuova riga alla fine.
Copia il nome della versione del secret che hai appena aggiunto. 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 secret in Client secret e incolla il nome della versione secret nella casella di input Versione secret.
- Se utilizzi la chiave API, seleziona Chiave API come Tipo di autenticazione, poi fai clic su Versione secret in Chiave API. Incolla il nome della versione del secret nella casella di input Versione del secret.
- Se utilizzi il token Bearer, seleziona Token Bearer come Tipo di autenticazione, poi fai clic su Versione secret in Token Bearer. Incolla il nome della versione del secret nella casella di input 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 alle destinazioni API all'interno della tua 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 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 al service account 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 API aperta derivano dalla conversazione degli utenti con l'LLM utilizzando lo schema come guida. In alcune situazioni, gli input potrebbero dover essere derivati dai parametri di sessione raccolti durante un flusso o forniti come input di un parametro di query insieme all'input utente.

Il parametro di sessione da trasmettere 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 alcun parametro di sessione, l'input generato dall'LLM verrà passato allo strumento.

Valori predefiniti dello strumento OpenAPI

Lo schema Open API può essere utilizzato per specificare i valori predefiniti. I valori predefiniti vengono utilizzati solo se non è presente un valore di input generato dal modello LLM o un valore di input basato su un parametro di sessione per quel parametro o proprietà.

I valori predefiniti possono essere specificati come parte dello schema nel seguente modo:

     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 dal modello LLM, valore parametro di sessione o valore predefinito, l'input non verrà specificato.

Strumenti per il datastore

Per informazioni sull'utilizzo degli strumenti del datastore con un playbook, consulta la documentazione relativa agli strumenti del datastore.

Strumenti per i connettori

Gli strumenti del connettore possono essere utilizzati da un agente per eseguire azioni utilizzando le tue connessioni configurate in Integration Connectors. Ogni strumento connettore è configurato con una singola connessione e una o più azioni. Se necessario, è possibile creare più strumenti per una singola connessione per raggruppare diverse azioni che l'agente può utilizzare.

Lo strumento di connessione supporta i seguenti tipi di connettori:

Gli esempi devono essere utilizzati per migliorare l'utilizzo degli strumenti del connettore da parte dell'agente mostrando come l'agente deve chiamare lo strumento e utilizzare la risposta.

Crea una connessione

Per creare una connessione e collegarla al tuo agente, puoi andare su Strumenti > Crea, selezionare il tipo di strumento Connettore, il tipo di connettore che hai scelto e utilizzare il pulsante Crea connessione. In questo modo, verrà visualizzata la creazione di Integration Connectors con un numero di campi precompilati.

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

Azioni del connettore

Per ogni strumento connettore, sono disponibili due tipi di azioni che possono essere rese disponibili per l'agente (per ulteriori informazioni, consulta Entità, operazioni e azioni):

Operazioni CRUD delle entità

Ogni connessione 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à:
- Create: crea un'entità con i valori dei campi specificati
- Elenco: ricerca basata su filtri delle istanze di entità
- Aggiornamento: metodo basato sui 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 filterClause per recuperare un'entità.

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

Molti connettori supportano un'azione "ExecuteCustomQuery", che consente di eseguire una query SQL sull'origine dati, in cui ogni entità dell'origine dati può essere referenziata 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

Selezionando campi di input o output specifici da utilizzare per l'azione dello strumento 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 mostrando solo i campi pertinenti.

Autenticazione

Se la connessione che utilizzi è configurata per consentire l'override dell'autenticazione, lo strumento può essere configurato per trasferire le credenziali dai parametri di sessione specificati.

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

Strumenti per le funzioni

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

La procedura è la seguente:

Il codice client invia una richiesta di rilevamento dell'intent.
L'agente rileva che è necessario uno strumento di funzione e la risposta di rilevamento dell'intent contiene il nome dello strumento insieme agli argomenti di input. Questa sessione è in pausa fino a quando non viene ricevuta un'altra richiesta di rilevamento dell'intent con il risultato dello strumento.
Il codice client chiama lo strumento.
Il codice client invia un'altra richiesta di rilevamento dell'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 iniziale di rilevamento dell'intent 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'intent, 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 datastore possono essere eseguiti 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
    }
  }
  ...
}