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 connettere i playbook a sistemi esterni. Questi sistemi possono migliorare 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 degli strumenti

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

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 doverli configurare manualmente.

Gli strumenti integrati supportati sono:

Code Interpreter: uno strumento proprietario di Google che combina la funzionalità di generazione ed esecuzione di codice e ti consente di eseguire varie attività, tra cui l'analisi dei dati, la visualizzazione dei dati, l'elaborazione del testo e la risoluzione di equazioni o problemi di ottimizzazione.

L'agente è ottimizzato per determinare come e quando richiamare questi strumenti, ma puoi fornire ulteriori esempi adatti ai tuoi casi d'uso.

Schema di esempio:

{
  "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à Strumento di test disponibile nella pagina dello strumento. Questa funzionalità è disponibile anche nella visualizzazione degli esempi 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

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 di Dialogflow CX 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 e header. Il tipo di parametro cookie non è supportato.
I parametri definiti dallo schema OpenAPI supportano i seguenti tipi di dati: string, number, integer, boolean e array. Il tipo object non è supportato.
Non puoi specificare parametri di ricerca nell'editor di esempi della console.
I corpi della richiesta e della risposta devono essere vuoti o utilizzare il formato application/json.

Generazione dello schema dello strumento OpenAPI

Quando fornisci uno schema, fai clic su Usa Gemini per creare lo schema utilizzando l'AI generativa.

Fornisci i seguenti dettagli per guidare la generazione:

Un URL di richiesta.
Un metodo HTTP, ad esempio GET o POST.
Input di esempio.
Esempio di output.
Un prompt testuale che descrive lo strumento.

Dopo aver generato lo schema, puoi modificarlo in base alle tue esigenze e aggiungere manualmente altri URL e metodi.

Autenticazione API dello strumento OpenAPI

Puoi utilizzare le seguenti opzioni di autenticazione quando chiami un'API esterna.

Autenticazione dell'agente di servizio Dialogflow CX

Dialogflow CX può generare un token ID utilizzando l'agente di servizio Dialogflow CX. Il token viene aggiunto nell'intestazione HTTP di autorizzazione quando Dialogflow CX chiama un'API esterna.

Puoi utilizzare un token ID per accedere ai servizi Cloud Run Functions e 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 i servizi Cloud Run Functions e Cloud Run si trovano nello stesso progetto di risorse, non sono necessarie autorizzazioni Identity and Access Management (IAM) aggiuntive per chiamarli.

Autenticazione del service account

I service account possono autenticare le richieste degli strumenti a qualsiasi API di Google che li supporti.

Se non l'hai ancora fatto, crea un service account. Poiché i service account sono entità, puoi concedere loro ruoli per accedere alle risorse nel tuo progetto, proprio come faresti per qualsiasi altra entità. Puoi utilizzare l'indirizzo email del service account per generare un token di accesso che invii nell'intestazione Authorization della richiesta dello strumento.

Se configuri lo strumento per l'utilizzo dei service account, devi disporre delle seguenti autorizzazioni:

roles/iam.serviceAccountUser

Per consentire a Dialogflow CX di generare token, concedi all'agente di servizio Dialogflow CX le seguenti autorizzazioni:

roles/iam.serviceAccountTokenCreator

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

Autenticazione con 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 CX 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:

Puoi utilizzare questo flusso se Generative AI App Builder è il proprietario della risorsa e non hai bisogno dell'autorizzazione dell'utente finale.
Devi configurare l'ID client, il client secret e l'endpoint del token da un provider OAuth in Dialogflow CX.
Ti consigliamo di fornire il client secret utilizzando Secret Manager. Gli agenti esportati non conterranno client secret con valori non elaborati dopo il 15 agosto 2025.
Dialogflow CX scambia un token di accesso OAuth da un provider OAuth e lo passa nell'intestazione di autorizzazione della richiesta.

Token di connessione

Puoi configurare l'autenticazione di connessione per passare dinamicamente il token di connessione dal client. Questo token è incluso nell'intestazione di autorizzazione della richiesta.
Quando configuri l'autenticazione dello strumento, puoi designare un parametro di sessione che funga da 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 di 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 fornirlo utilizzando Secret Manager. Dopo il 15 agosto 2025, gli agenti esportati non conterranno token di connessione con valori non elaborati.

Autenticazione TLS reciproca

Per saperne di più, consulta 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 i webhook.

Certificato CA personalizzato

Per ulteriori informazioni, consulta Certificati CA personalizzati.

Autenticazione di Secret Manager

Se utilizzi OAuth, una chiave API o un token di connessione, puoi archiviare le credenziali come secret utilizzando Secret Manager.

Per autenticare lo strumento utilizzando i secret, segui questi passaggi:

Se non ne hai già uno, crea il tuo secret.
Concedi all'agente di servizio Dialogflow il ruolo Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) sul nuovo secret.
Copia la credenziale 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 del valore del secret.
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 immissione Versione secret.
- Se utilizzi la chiave API, seleziona Chiave API come Tipo di autenticazione, quindi fai clic su Versione 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 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 dello strumento OpenAPI

Lo strumento OpenAPI si integra con l'accesso alla rete privata di Service Directory per connettersi ai target API nella tua rete VPC. In questo modo, il traffico rimane all'interno della rete Google Cloud e vengono applicati IAM e i 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.
Assicurati che il service account Dialogflow CX Service Agent con il seguente indirizzo esista per il progetto dell'agente:
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Concedi al account di servizio Dialogflow CX Service Agent 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 di sessione dello strumento OpenAPI

Gli input dello strumento OpenAPI derivano dalla conversazione dell'utente con l'LLM utilizzando lo schema come guida. In alcune situazioni, potrebbe essere necessario ricavare gli input dai parametri di sessione raccolti durante un flusso o fornirli come input di parametri di query insieme all'input utente dell'utente.

Puoi specificare i parametri di sessione che devi passare come input utilizzando il seguente formato:

     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: Breed of the pet.

Se non sono disponibili parametri di sessione di questo tipo, l'input generato dall'LLM viene passato allo strumento.

Valori predefiniti dello strumento OpenAPI

Puoi utilizzare lo schema OpenAPI per specificare i valori predefiniti. Questi valori predefiniti vengono applicati solo quando non è disponibile un valore di input generato da LLM o un valore di input basato su parametri di sessione per quel parametro o quella proprietà.

Puoi specificare i valori predefiniti nello 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: Breed 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 di sessione o valore predefinito, l'input non verrà specificato.

Strumenti del datastore

Per ulteriori informazioni sull'utilizzo degli strumenti del datastore con un playbook, consulta la sezione sugli strumenti del datastore.

Strumenti del connettore

Gli strumenti di connettore ti consentono di configurare un agente per eseguire azioni utilizzando le connessioni configurate in Integration Connectors. Ogni strumento connettore è configurato con una singola connessione e una o più azioni. Puoi creare più strumenti per una singola connessione per raggruppare diverse azioni che l'agente può utilizzare.

Lo strumento connettore supporta i seguenti tipi di connettori:

Puoi utilizzare gli esempi per aiutare gli agenti a utilizzare gli strumenti del connettore in modo efficace, mostrando come chiamare gli strumenti e utilizzare le risposte.

Crea una connessione

Per creare una connessione e collegarla al tuo agente, vai a Strumenti > Crea, seleziona il tipo di strumento Connettore e il tipo di connettore scelto, quindi fai clic su Crea connessione. In questo modo si apre la creazione di Integration Connectors con diversi campi precompilati.

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

Azioni del connettore

Puoi rendere disponibili due tipi di azioni per l'agente per ogni strumento connettore. Per saperne di più, consulta Entità, operazioni e azioni.

Operazioni CRUD sulle entità:

Ogni connessione ha entità corrispondenti agli oggetti dell'origine dati (per BigQuery, si tratta di tabelle; per Salesforce, si tratta di oggetti, come Order o Case).

Puoi eseguire operazioni CRUD su ogni entità:
- Crea: convalida e crea un'entità con i valori dei campi specificati.
- List: ricerca basata su filtri delle istanze di entità.
- Aggiorna: metodo basato su filtri per modificare i valori dei campi delle entità.
- Elimina: elimina un'entità.
- Get: recupera una singola entità utilizzando l'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 un filterClause per recuperare un'entità.

Per saperne di più sulle operazioni CRUD delle entità, consulta la documentazione di Connectors.
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 indicata come tabella. Per saperne di più, consulta l'elenco dei 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.

Configura i campi di input/output per le operazioni CRUD

Selezionando campi di input o output specifici 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 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 per mitigare i limiti di token. In questo modo, l'agente può gestire l'output esponendo solo i campi pertinenti.

Autenticazione

Se la connessione che utilizzi consente l'override dell'autenticazione, configura lo strumento in modo che trasmetta le credenziali dai parametri di sessione specificati.

Inserisci queste credenziali nei parametri della sessione. Lo strumento li trasmette automaticamente all'origine dati per l'autenticazione quando vengono chiamate le azioni.

Strumenti di funzione

Se hai funzionalità accessibili dal codice client, ma non dagli strumenti OpenAPI, puoi utilizzare gli strumenti delle funzioni. Il lato client esegue sempre gli strumenti di funzione anziché l'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 viene messa in pausa fino alla ricezione di 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 iniziali 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

Puoi eseguire gli strumenti OpenAPI e datastore sul lato client, in modo simile agli strumenti di funzione, applicando un override dell'API quando interagisci con la sessione.