Alcuni prodotti e funzionalità sono in fase di ridenominazione. Anche le funzionalità di playbook generativo e flusso vengono migrate in un'unica console consolidata.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Strumenti di playbook

Utilizzando 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 creare strumenti personalizzati in base alle tue esigenze.

Test degli strumenti

Una volta creato uno strumento, puoi utilizzare la funzionalità di test dello strumento per verificare che funzioni. Quando visualizzi uno strumento, fai clic sul pulsante Test sopra il riquadro dello strumento. Lo strumento si aprirà per l'input nel simulatore. Fornisci l'input dello strumento, quindi fai clic su Visualizza output per verificare che l'output dello strumento sia corretto.

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 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 eseguire 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 richiamare 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 dello 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

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

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

Limitazioni degli strumenti 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 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 degli strumenti OpenAPI

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

Un URL della richiesta
Un metodo HTTP (GET, POST e così via)
Input di esempio
Output di esempio
Un prompt testuale che descrive lo strumento

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

Autenticazione API degli strumenti 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 ruoli 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 dell'account di servizio

I service account possono essere utilizzati per autenticare le richieste degli strumenti a qualsiasi API di Google che li 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'indirizzo email del account di servizio verrà utilizzato 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é Dialogflow CX generi i token, il agente di servizio Dialogflow deve disporre delle seguenti autorizzazioni:

roles/iam.serviceAccountTokenCreator

Il account di servizio deve inoltre disporre 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 passi la chiave API 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 di Vertex AI 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 client secret utilizzando Secret Manager. Dopo il 15 agosto 2025, gli agenti esportati non conterranno più client secret con valori non elaborati.
- Dialogflow scambia un token di accesso OAuth dal provider 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 sul lato client.
2. A questo punto puoi:
  
  a. Utilizzare l'opzione di autenticazione con token di connessione per passare il token allo strumento OpenAPI. Dialogflow includerà questo token nell'intestazione di autorizzazione quando richiama lo strumento.
  
  b. Utilizzare 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 con token di connessione per passare dinamicamente il token di connessione dal client. Questo token è incluso nell'intestazione di autenticazione della richiesta.
Quando configuri l'autenticazione dello strumento, puoi designare un parametro sessione come token di connessione. Ad esempio, utilizza $session.params.<parameter-name-for-token> per specificare il token.

In fase di runtime, assegna il token di connessione 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 sessione, ti consigliamo di fornire il token utilizzando Secret Manager. Dopo il 15 agosto 2025, gli agenti esportati non conterranno più token di connessione con valori non elaborati.

Autenticazione TLS reciproca

Consulta la documentazione sull'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 il mutual TLS per tutti gli strumenti e i webhook.

Certificato CA personalizzato

Consulta la documentazione sui certificati CA personalizzati.

Autenticazione di Secret Manager

Se utilizzi OAuth, la chiave API o il token di connessione, puoi archiviare le credenziali come secret utilizzando Secret Manager. Di seguito sono riportati i passaggi necessari per autenticare lo strumento utilizzando i secret:

Crea il secret se non ne hai già uno.
Concedi a Dialogflow Service Agent il ruolo Funzione di accesso ai secret di Secret Manager (roles/secretmanager.secretAccessor) per il nuovo secret.
Copia le credenziali negli appunti.
Aggiungi una nuova versione del secret al secret. Incolla le credenziali come valore del secret.
- Ometti qualsiasi carattere 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, quindi fai clic su Versione del secret in Client secret e incolla il nome della versione del secret nella casella di immissione Versione del secret.
- Se utilizzi la chiave API, seleziona Chiave API come Tipo di autenticazione, quindi fai clic su Versione del secret in Chiave API. Incolla il nome della versione del secret nella casella di immissione Versione del secret.
- Se utilizzi il token di connessione, seleziona Token di connessione come Tipo di autenticazione, quindi fai clic su Versione del secret in Token di connessione. Incolla il nome della versione del secret nella casella di immissione Versione del secret.
Fai clic su Salva.

Accesso alla rete privata degli strumenti OpenAPI

Lo strumento OpenAPI si integra con l'accesso alla rete privata di Service Directory, quindi può connettersi alle destinazioni 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 il service account 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
Quando crei lo strumento, fornisci il servizio Service Directory insieme allo schema OpenAPI e alle informazioni di autenticazione facoltative.

Accesso ai parametri sessione degli strumenti OpenAPI

Gli input degli strumenti OpenAPI derivano dalla conversazione degli utenti con l'LLM utilizzando lo schema come guida. In alcune situazioni, gli input potrebbero dover essere derivati dai parametri sessione raccolti durante un flusso o forniti come input di parametri di query insieme all'input utente.

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

Valori predefiniti degli strumenti OpenAPI

Lo schema OpenAPI può essere utilizzato per specificare i valori predefiniti. I valori predefiniti vengono utilizzati solo se non è presente un valore di input generato dall'LLM o un valore di input basato su parametri 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 dall'LLM, valore parametro sessione o valore predefinito, l'input non verrà specificato.

Strumenti datastore

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

Strumenti connettore

Un agente può utilizzare gli strumenti connettore per eseguire azioni utilizzando le 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 da utilizzare per l'agente.

Lo strumento connettore supporta i seguenti tipi di connettori:

Gli esempi devono essere utilizzati per migliorare l'utilizzo degli strumenti connettore da parte dell'agente, dimostrando come l'agente deve 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 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à:
- Crea: crea un'entità con i valori dei campi specificati
- Elenca: ricerca di istanze di entità basata su filtri
- Aggiorna: metodo basato su filtri per modificare i valori dei campi delle entità
- Elimina: elimina un'entità
- Ottieni : recupera una singola entità utilizzando l'entityId
Nota: l'operazione Ottieni può essere utilizzata solo per recuperare un singolo record da un' entità che ha una chiave primaria. Spesso è più pratico utilizzare l'operazione Elenca con una filterClause per recuperare un'entità.

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

Molti connettori supportano un' 'ExecuteCustomQuery' azione, che consente di eseguire una query SQL sull'origine dati, in cui è possibile fare riferimento a ciascuna delle entità dell'origine dati come tabelle. 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 per l'azione dello strumento connettore da utilizzare, puoi limitare la complessità di queste azioni per l'agente.

Ad esempio, se devi creare un'entità solo con un sottoinsieme dei suoi 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 dei token sono un problema) e semplifica la gestione dell'output da parte dell'agente esponendo solo i campi pertinenti.

Autenticazione

Se la connessione che stai utilizzando è configurata per consentire la sostituzione dell'autenticazione, lo strumento può essere configurato per passare le credenziali dai parametri sessione specificati.

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

Strumenti funzione

Se hai funzionalità accessibili dal codice client, ma non dagli strumenti OpenAPI, puoi utilizzare gli strumenti 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 funzione e la risposta di rilevamento dell'intent contiene il nome dello strumento insieme agli argomenti di input. Questa sessione viene sospesa 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 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 di rilevamento dell'intent iniziale 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 funzione, gli strumenti OpenAPI e datastore possono essere eseguiti sul lato client applicando una sostituzione dell'API durante l'interazione con la sessione.

Ad esempio:

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