Certains produits et fonctionnalités sont en cours de changement de nom. Les fonctionnalités de playbook et de flux génératifs sont également en cours de migration vers une console unique. Consultez les détails.

Cette page a été traduite par l'API Cloud Translation.

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 pour répondre à vos besoins.

Test des outils

Une fois que vous avez créé un outil, vous pouvez utiliser la fonctionnalité de test d'outil pour vérifier qu'il fonctionne. Lorsque vous consultez un outil, cliquez sur le bouton Tester au-dessus du volet de l'outil. L'outil de saisie s'ouvre dans le simulateur. Fournissez l'entrée de l'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 activer ces outils dans les agents sans avoir à les configurer manuellement.

Voici les outils intégrés compatibles :

Code Interpreter : outil Google first party qui combine la génération et l'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 l'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 schéma OpenAPI. Par défaut, l'agent appellera l'API en votre nom.

Vous pouvez vérifier que l'outil est correctement configuré à l'aide de la fonctionnalité de test 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 pour 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é.
Pour le moment, vous ne pouvez pas spécifier de paramètres de requête dans l'éditeur d'exemples 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émas d'outils OpenAPI

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

URL de la demande
Méthode HTTP (GET, POST, etc.)
Exemple d'entrée
Exemple de sortie
Une requête textuelle décrivant l'outil

Une fois le schéma généré, vous pouvez le modifier si nécessaire et ajouter manuellement d'autres URL et méthodes.

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'identité à l'aide de l'agent de service Dialogflow. Le jeton est ajouté à 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 à 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 compatibles.

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 les agents conversationnels (Dialogflow CX) puissent générer 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 avec des valeurs brutes.

OAuth

Le flux d'identifiants client OAuth est compatible avec l'authentification de serveur à serveur :
- Ce flux peut être utilisé si la console Applications d'IA est le propriétaire de la ressource et qu'aucune autorisation de l'utilisateur final n'est requise.
- L'ID client, le code secret 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 de client bruts.
- 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 l'autorisation de l'utilisateur final, comme le flux avec code d'autorisation et le flux PKCE :
1. Vous devrez implémenter votre propre UI de connexion et obtenir le jeton d'accès côté client.
2. Vous pouvez alors :
  
  a. Utilisez 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. Utilisez l'outil Fonction pour appeler l'outil vous-même côté client et transmettre le résultat de l'appel d'outil à Dialogflow.

Jeton de support

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

Lors de l'exécution, attribuez le jeton Bearer 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 de l'extraire 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 Bearer bruts.

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, dans l'onglet "Sécurité" des paramètres de l'agent. Les champs "Certificat (format PEM)" et "Clé privée (format PEM)" sont obligatoires. Une fois défini, ce certificat client sera utilisé lors du protocole TLS mutuel pour tous les outils et les Webhooks.

Certificat CA personnalisé

Consultez la documentation sur les certificats CA personnalisés.

Authentification Secret Manager

Si vous utilisez OAuth, une clé API ou un jeton Bearer, 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 encore.
Attribuez le rôle Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) à l'agent de service Dialogflow sur le nouveau secret.
Copiez vos identifiants dans le presse-papiers.
Ajoutez une 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 du 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 le champ 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é :

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 des paramètres de session collectés au cours 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 à transmettre en tant qu'entrée peut être spécifié comme suit :

     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 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 LLM, valeur de paramètre de session ou valeur par défaut n'est présente, l'entrée ne sera pas spécifiée.

Outils de data store

Pour savoir comment utiliser les outils de data store avec un playbook, consultez la documentation sur les outils de data store.

Outils de connecteur

Un agent peut utiliser les outils de connecteur 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 l'associer à 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 du 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 les entités

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 champ spécifiées
- Liste : recherche basée sur des filtres pour les instances d'entités
- Update : méthode basée sur les filtres pour modifier les valeurs des champs d'entité
- Supprimer : supprime une entité
- Get récupère une seule entité à l'aide de l'entityId
  .
Remarque : L'opération Get ne peut être utilisée que pour extraire un seul enregistrement d'une entité disposant d'une clé primaire. Il est souvent plus pratique d'utiliser l'opération List avec une filterClause pour récupérer une entité.

Pour en savoir plus sur les opérations CRUD d'entité, consultez la documentation sur les connecteurs.
Actions spécifiques aux connecteurs

De nombreux connecteurs sont compatibles avec l'action ExecuteCustomQuery, 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 la liste des 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.

Configurer les 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 l'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.

Spécifier 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 le traitement 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'agents, vous êtes responsable de la façon 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 sont appelées.

Outils de fonction

Si votre code client vous permet d'accéder à des fonctionnalités qui ne sont pas accessibles par les outils OpenAPI, vous pouvez utiliser des 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 suspendue 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 detect 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
    }
  }
  ...
}