Le nom de certains produits et fonctionnalités est en cours de modification. Les fonctionnalités de playbook génératif et de flux sont également en cours de migration vers une seule console consolidée.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Outils de playbook

Les outils vous permettent de connecter des playbooks à des systèmes externes. Ces systèmes peuvent améliorer les connaissances des playbooks et leur donner les moyens d'exécuter efficacement des tâches complexes.

Vous pouvez utiliser des outils intégrés ou créer des outils personnalisés adaptés à vos besoins.

Test des outils

Une fois que vous avez créé un outil, vous pouvez utiliser la fonctionnalité de test pour vérifier qu'il fonctionne. Lorsque vous affichez un outil, cliquez sur le bouton Test au-dessus du volet de l'outil. L'outil s'ouvre pour la saisie dans le simulateur. Fournissez une entrée d'outil, puis cliquez sur Afficher la sortie pour vérifier que la sortie de l'outil est correcte.

Vous pouvez également utiliser la fonctionnalité de test d'outil lorsque vous ajoutez un outil à un exemple.

Outils intégrés

Les outils intégrés sont hébergés par Google. Vous pouvez les activer dans les agents sans avoir à les configurer manuellement.

Les outils intégrés compatibles sont les suivants :

Code Interpreter : outil first party de Google qui combine la capacité de génération et d'exécution de code, et qui permet à l'utilisateur d'effectuer diverses tâches, y compris l'analyse et la visualisation de données, le traitement de texte, la résolution d'équations ou de problèmes d'optimisation.

Votre agent est optimisé pour déterminer comment et quand ces outils doivent être appelés, mais vous pouvez fournir des exemples supplémentaires pour les adapter à vos cas d'utilisation.

Les exemples doivent avoir un schéma semblable à celui-ci :

{
  "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"
        }
      }
    ]
  }
}

Outils OpenAPI

Un agent peut se connecter à une API externe à l'aide d'un outil OpenAPI en fournissant le OpenAPI. Par défaut, l'agent appelle l'API en votre nom.

Vous pouvez vérifier que l'outil est correctement configuré à l'aide de la fonctionnalité "Test tool" (Tester l'outil) disponible sur la page de l'outil. Cette fonctionnalité est également disponible dans la vue d'exemple lorsque vous ajoutez un appel d'outil à l'exemple.

Vous pouvez également exécuter des outils OpenAPI côté client.

Exemple de schéma :

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

Vous pouvez éventuellement utiliser la référence de schéma interne @dialogflow/sessionId comme type de schéma de paramètre. Avec ce type de schéma de paramètre, l'ID de session Dialogflow de la conversation en cours sera fourni en tant que valeur de paramètre. Exemple :

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

Limites des outils OpenAPI

Les limites suivantes s'appliquent :

Les types de paramètres acceptés sont path, query et header. Le type de paramètre cookie n'est pas encore accepté.
Les paramètres définis par le schéma OpenAPI sont compatibles avec les types de données suivants : string, number, integer, boolean et array. Le type object n'est pas encore accepté.
Vous ne pouvez actuellement pas spécifier de paramètres de requête dans l'éditeur d'exemple de la console.
Le corps de la requête et de la réponse doit être vide ou au format JSON.

Génération de schéma d'outil OpenAPI

Lorsque vous fournissez un schéma, vous pouvez utiliser le bouton Utiliser Gemini pour utiliser l'IA générative afin de créer votre schéma. Vous pouvez fournir les éléments suivants pour guider la génération :

Une URL de requête
Une méthode HTTP (GET, POST, etc.)
Exemple d'entrée
Exemple de sortie
Un prompt textuel décrivant l'outil

Une fois le schéma généré, vous pouvez le modifier si nécessaire et ajouter manuellement des URL et des méthodes supplémentaires.

Authentification de l'API de l'outil OpenAPI

Les options d'authentification suivantes sont acceptées lors de l'appel d'une API externe :

Authentification de l'agent de service Dialogflow

Dialogflow peut générer un jeton d'ID à l'aide de l'agent de service Dialogflow. Le jeton est ajouté dans l'en-tête HTTP d'autorisation lorsque Dialogflow appelle une API externe.

Un jeton d'ID peut être utilisé pour accéder aux fonctions Cloud Run et aux services Cloud Run après avoir attribué les rôles roles/cloudfunctions.invoker et roles/run.invoker rôles à service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Si les fonctions Cloud Run et les services Cloud Run se trouvent dans le même projet de ressources, vous n'avez pas besoin d'autorisation IAM supplémentaire pour les appeler.

Authentification par compte de service

Les comptes de service peuvent être utilisés pour authentifier les requêtes d'outils auprès de toutes les API Google qui les acceptent.

Si ce n'est pas déjà fait, créez un compte de service.

Comme les comptes de service sont des comptes principaux, ils peuvent accéder aux ressources de votre projet en leur attribuant un rôle, comme vous le feriez pour n'importe quel autre compte principal. L'adresse e-mail du compte de service sera utilisée pour générer un jeton d'accès qui sera envoyé dans l'en-tête Authorization de la requête d'outil.

L'utilisateur qui configure l'outil pour utiliser des comptes de service doit disposer des autorisations suivantes :

roles/iam.serviceAccountUser

Pour que Dialogflow CX génère des jetons, l' agent de service Dialogflow doit disposer des autorisations suivantes :

roles/iam.serviceAccountTokenCreator

Le compte de service doit également disposer des autorisations nécessaires pour accéder au service qui héberge l'outil.

Clé API

Vous pouvez configurer l'authentification par clé API en fournissant le nom de la clé, l'emplacement de la requête (en-tête ou chaîne de requête) et la clé API afin que Dialogflow transmette la clé API dans la requête.
Nous vous recommandons de fournir votre clé API à l'aide de Secret Manager. Après le 15 août 2025, les agents exportés ne contiendront plus de clés API de valeur brute.

OAuth

Le flux d'identifiants client OAuth est compatible avec l'authentification de serveur à serveur :
- Ce flux peut être utilisé si la console Vertex AI Agent Builder est le propriétaire de la ressource et qu'aucune autorisation de l'utilisateur final n'est requise.
- L'ID client, le code secret du client et le point de terminaison du jeton du fournisseur OAuth doivent être configurés dans Dialogflow.
  - Nous vous recommandons de fournir votre code secret du client à l'aide de Secret Manager. Après le 15 août 2025, les agents exportés ne contiendront plus de codes secrets client de valeur brute.
- Dialogflow échange un jeton d'accès OAuth auprès du fournisseur OAuth et le transmet dans l'en-tête d'authentification de la requête.
Pour les autres flux OAuth qui nécessitent une autorisation de l'utilisateur final, comme le flux avec code d'autorisation et le flux PKCE :
1. Vous devrez implémenter votre propre interface utilisateur de connexion et obtenir le jeton d'accès côté client.
2. Vous pouvez alors :
  
  a. Utiliser l'option d'authentification par jeton de support pour transmettre le jeton à l'outil OpenAPI. Dialogflow inclura ce jeton dans l'en-tête d'autorisation lors de l'appel de l'outil.
  
  b. Utiliser l'outil de fonction pour appeler vous-même l'outil côté client et transmettre le résultat de l'appel d'outil à Dialogflow.

Jeton de support

Vous pouvez configurer l'authentification par support pour transmettre dynamiquement le jeton de support à partir du client. Ce jeton est inclus dans l'en-tête d'authentification de la requête.
Lorsque vous configurez l'authentification de l'outil, vous pouvez désigner un paramètre de session comme jeton de support. Par exemple, utilisez $session.params.<parameter-name-for-token> pour spécifier le jeton.

Lors de l'exécution, attribuez le jeton de support au paramètre de session :

DetectIntentRequest {
  ...
  query_params {
    parameters {
      <parameter-name-for-token>: <the-auth-token>
    }
  }
  ...
}

Si vous devez configurer un jeton statique au lieu d'extraire le jeton d'un paramètre de session, nous vous recommandons de fournir votre jeton à l'aide de Secret Manager. Après le 15 août 2025, les agents exportés ne contiendront plus de jetons de support de valeur brute.

Authentification TLS mutuelle

Consultez la documentation sur l'authentification TLS mutuelle.
Les certificats client personnalisés sont acceptés. Vous pouvez configurer des certificats client au niveau de l'agent sous l'onglet "Sécurité" des paramètres de l'agent. Le certificat (au format PEM) et la clé privée (au format PEM) sont des champs obligatoires. Une fois défini, ce certificat client sera utilisé lors de l'authentification TLS mutuelle pour tous les outils et webhooks.

Certificat CA personnalisé

Consultez la documentation sur les certificats CA personnalisés.

Authentification par Secret Manager

Si vous utilisez OAuth, une clé API ou un jeton de support, vous pouvez stocker les identifiants en tant que secrets à l'aide de Secret Manager. Voici les étapes nécessaires pour authentifier votre outil à l'aide de secrets :

Créez votre secret si vous n'en avez pas déjà un.
Attribuez le rôle Agent de service Dialogflow Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) au nouvel agent de service.
Copiez vos identifiants dans le presse-papiers.
Ajoutez une nouvelle version de secret à votre secret. Collez vos identifiants en tant que valeur du secret.
- Omettez tout caractère de nouvelle ligne à la fin.
Copiez le nom de la version de secret que vous venez d'ajouter. Le format du nom est projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
Ouvrez l'écran de modification de l'outil, puis :
- Si vous utilisez OAuth, sélectionnez OAuth comme type d'authentification, puis cliquez sur Version du secret sous Code secret du client et collez le nom de la version du secret dans la zone de saisie Version du secret.
- Si vous utilisez une clé API, sélectionnez Clé API comme type d'authentification, puis cliquez sur Version du secret sous Clé API. Collez le nom de la version du secret dans la zone de saisie Version du secret.
- Si vous utilisez un jeton de support, sélectionnez Jeton de support comme type d'authentification, puis cliquez sur Version du secret sous Jeton de support. Collez le nom de la version du secret dans la zone de saisie Version du secret.
Cliquez sur Enregistrer.

Accès au réseau privé de l'outil OpenAPI

L'outil OpenAPI s'intègre à l'accès au réseau privé de l'Annuaire des services, pour pouvoir se connecter aux cibles d'API dans votre réseau VPC. Cela permet de conserver le trafic au sein du réseau Google Cloud et d'appliquer IAM et VPC Service Controls.

Pour configurer un outil OpenAPI ciblant un réseau privé, procédez comme suit :

Suivez la page sur la configuration du réseau privé de l'Annuaire des services pour configurer votre réseau VPC et le point de terminaison de l'Annuaire des services.
Le compte de service Agent de service Dialogflow avec l'adresse suivante doit exister pour votre projet d'agent :
```
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
```
Attribuez les rôles IAM suivants au compte de service Agent de service Dialogflow :
- servicedirectory.viewer du projet de l'Annuaire des services
- servicedirectory.pscAuthorizedService du projet réseau
Fournissez le service d'annuaire du service avec le schéma OpenAPI et les informations d'authentification facultatives lors de la création de l'outil.

Accès aux paramètres de session de l'outil OpenAPI

Les entrées de l'outil Open API sont dérivées de la conversation des utilisateurs avec le LLM à l'aide du schéma comme guide. Dans certains cas, les entrées peuvent devoir être dérivées de paramètres de session collectés lors d'un flux ou fournis en tant qu'entrée de paramètre de requête avec l'entrée utilisateur.

Le paramètre de session qui doit être transmis en tant qu'entrée peut être spécifié comme

     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.

Si aucun paramètre de session de ce type n'est disponible, l'entrée générée par le LLM sera transmise à l'outil.

Valeurs par défaut de l'outil OpenAPI

Le schéma Open API peut être utilisé pour spécifier des valeurs par défaut. Les valeurs par défaut ne sont utilisées que s'il n'existe aucune valeur d'entrée générée par le LLM ni aucune valeur d'entrée basée sur un paramètre de session pour ce paramètre ou cette propriété.

Les valeurs par défaut peuvent être spécifiées dans le schéma comme suit :

     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

Si aucune valeur générée par le LLM, aucune valeur de paramètre de session ni aucune valeur par défaut n'est présente, l'entrée ne sera pas spécifiée.

Outils de datastore

Pour en savoir plus sur l'utilisation des outils de data store avec un playbook, consultez la documentation sur les outils de datastore.

Outils de connecteur

Les outils de connecteur peuvent être utilisés par un agent pour effectuer des actions à l'aide de vos connexions configurées dans Integration Connectors. Chaque outil de connecteur est configuré avec une seule connexion et une ou plusieurs actions. Si nécessaire, vous pouvez créer plusieurs outils pour une même connexion afin de regrouper différentes actions que votre agent pourra utiliser.

L'outil de connecteur est compatible avec les types de connecteurs suivants :

Les exemples doivent être utilisés pour améliorer l'utilisation des outils de connecteur par l'agent en montrant comment l'agent doit appeler l'outil et utiliser la réponse.

Créer une connexion

Pour créer une connexion et la connecter à votre agent, accédez à Outils > Créer, sélectionnez le type d'outil Connecteur, le type de connecteur de votre choix, puis cliquez sur le bouton Créer une connexion. Vous serez redirigé vers la création d'Integration Connectors avec un certain nombre de champs préremplis.

Vous pouvez également accéder à Integration Connectors et suivre les instructions pour créer une connexion.

Actions de connecteur

Pour chaque outil de connecteur, deux types d'actions peuvent être mis à la disposition de votre agent (pour en savoir plus, consultez Entités, opérations et actions ) :

Opérations CRUD sur une entité

Chacune de vos connexions comporte des "entités" correspondant aux objets de cette source de données (pour BigQuery, il s'agit de tables ; pour Salesforce, il s'agit d'objets, comme "Commande" ou "Requête").

Vous pouvez effectuer des opérations CRUD sur chaque entité :
- Créer : crée une entité avec les valeurs de champs spécifiées
- Liste : recherche des instances d'entité en fonction de filtres
- Mettre à jour : modifie des valeurs de champs d'entité en fonction de filtres
- Supprimer : supprime une entité
- Obtenir : récupère une entité à l'aide de son ID
Remarque : L’opération « Obtenir » ne peut être utilisée que pour extraire un seul enregistrement d’une entité contenant une clé primaire. Il est souvent plus pratique d'utiliser l'opération "Liste" avec une filterClause pour récupérer une entité.

Pour en savoir plus sur les opérations CRUD sur les entités, consultez la documentation sur les connecteurs.
Actions spécifiques au connecteur

De nombreux connecteurs sont compatibles avec une 'ExecuteCustomQuery' action, qui permet d'exécuter une requête SQL sur la source de données, où chacune des entités de la source de données peut être référencée en tant que table. Consultez cette liste pour connaître les connecteurs compatibles.

Les actions supplémentaires varient en fonction du type de connecteur. Par exemple, consultez les actions du connecteur BigQuery ou les actions du connecteur Salesforce.

Configuration des champs d'entrée / de sortie pour les opérations CRUD

En sélectionnant des champs d'entrée ou de sortie spécifiques à utiliser pour l'action de votre outil de connecteur, vous pouvez limiter la complexité de ces actions pour l'agent.

Par exemple, si vous n'avez besoin de créer une entité qu'avec un sous-ensemble de ses champs, la configuration de cet ensemble de champs dans votre action simplifie l'action pour l'agent.

La spécification d'un ensemble de champs de sortie réduit la taille de la réponse de l'outil (utile si les limites de jetons sont un problème) et simplifie la gestion de la sortie par l'agent en n'exposant que les champs pertinents.

Authentification

Si la connexion que vous utilisez est configurée pour autoriser le remplacement de l'authentification, l'outil peut être configuré pour transmettre les identifiants à partir des paramètres de session spécifiés.

En tant que créateur d'agent, vous êtes responsable de la manière dont ces identifiants sont renseignés dans les paramètres de session. L'outil les transmettra automatiquement à la source de données pour l'authentification lorsque les actions de l'outil seront appelées.

Outils de fonction

Si vous disposez de fonctionnalités accessibles à votre code client, mais pas aux outils OpenAPI, vous pouvez utiliser les outils de fonction. Les outils de fonction sont toujours exécutés côté client, et non par l'agent.

Le processus est le suivant :

Votre code client envoie une requête de détection d'intent.
L'agent détecte qu'un outil de fonction est requis, et la réponse de détection d'intent contient le nom de l'outil ainsi que les arguments d'entrée. Cette session est mise en pause jusqu'à ce qu'une autre requête de détection d'intent soit reçue avec le résultat de l'outil.
Votre code client appelle l'outil.
Votre code client envoie une autre requête de détection d'intent qui fournit le résultat de l'outil en tant qu'arguments de sortie.

L'exemple suivant montre le schéma d'entrée et de sortie d'un outil de fonction :

{
  "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'exemple suivant montre la requête et la réponse initiales de détection d'intent à l'aide de 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'exemple suivant montre la deuxième requête de détection d'intent, qui fournit le résultat de l'outil :

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

Exécution côté client

Comme les outils de fonction, les outils OpenAPI et de data store peuvent être exécutés côté client en appliquant un remplacement d'API lors de l'interaction avec la session.

Exemple :

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