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 d'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 affichez un outil, cliquez sur le bouton Tester au-dessus du volet de l'outil. L'outil de saisie s'ouvre 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 activer ces outils dans les agents sans configuration manuelle.

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

Code Interpreter : outil propriétaire de Google qui combine les fonctionnalités de génération et d'exécution de code, et permet à l'utilisateur d'effectuer diverses tâches, y compris l'analyse de données, 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 adaptés à 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é "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 accepté.
Les paramètres définis par le schéma OpenAPI sont compatibles avec les types de données suivants : string, number, integer, boolean, array. Le type object n'est pas accepté.
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 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 fichier 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 compatibles 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é à 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.. Si les fonctions Cloud Run et les services Cloud Run se trouvent dans le même projet de ressource, vous n'avez pas besoin d'une autorisation Identity and Access Management 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 de l'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 puisse 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 de valeur brute.

OAuth

Le flux d'identifiants client OAuth est compatible avec l'authentification de serveur à serveur :
- Ce flux peut être utilisé si Generative AI App 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 d'un 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 du client en valeur brute.
- Dialogflow échange un jeton d'accès OAuth d'un fournisseur OAuth et le transmet dans l'en-tête d'authentification de la requête.

Jeton de support

Vous pouvez configurer l'authentification Bearer pour transmettre dynamiquement le jeton Bearer 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 qui servira de jeton de support. Par exemple, utilisez $session.params.<parameter-name-for-token> pour spécifier le jeton.

Au moment 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 de récupérer le jeton à partir 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 clients au niveau de l'agent dans l'onglet "Sécurité" des paramètres de l'agent. Le certificat (format PEM) et la clé privée (format PEM) sont des champs obligatoires. Une fois défini, ce certificat client sera utilisé lors du protocole TLS mutuel pour tous les outils et 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 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 à l'agent de service Dialogflow le rôle Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) sur le nouveau secret.
Copiez votre identifiant dans le presse-papiers.
Ajoutez une nouvelle version de secret à votre secret. Collez votre identifiant comme 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 le champ 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 le champ de saisie Version du secret.
Cliquez sur Enregistrer.

Accès à un réseau privé pour l'outil OpenAPI

L'outil OpenAPI s'intègre à l'accès au réseau privé de l'Annuaire des services, ce qui lui permet de se connecter aux cibles d'API de votre réseau VPC. Le trafic reste ainsi au sein du réseau Google Cloud et applique 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.
```
Attribuez au compte de service Agent de service Dialogflow les rôles Identity and Access Management suivants :
- servicedirectory.viewer du projet de l'Annuaire des services
- servicedirectory.pscAuthorizedService du projet réseau
Fournissez le service d'annuaire des services, ainsi que 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 OpenAPI sont dérivées de la conversation de l'utilisateur avec le LLM en utilisant le schéma comme guide. Dans certains cas, les entrées peuvent devoir être dérivées des paramètres de session collectés lors d'un flux ou fournies 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 est transmise à l'outil.

Valeurs par défaut de l'outil OpenAPI

Le schéma OpenAPI 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 pas de valeur d'entrée générée par le LLM ou de 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, 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 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 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 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 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 "Demande").

Vous pouvez effectuer des opérations CRUD sur chaque entité :
- Create : crée une entité avec les valeurs de champs spécifiées
- List : recherche des instances d'entité en fonction de filtres
- Update : modifie des valeurs de champs d'entité en fonction de filtres
- 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é contenant 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 au connecteur

De nombreux connecteurs sont compatibles avec une 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 diffèrent selon le type de connecteur. Par exemple, consultez les actions du connecteur BigQuery ou les actions du connecteur Salesforce.

Configurer les champs d'entrée/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, configurer 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 (ce qui est 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 de l'agent, 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 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'intention.
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'intention 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.