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
Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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 en fonction de vos besoins.

Test de l'outil

Une fois que vous avez créé un outil, vous pouvez utiliser la fonctionnalité de test de l'outil pour vérifier qu'il fonctionne. Lorsque vous consultez un outil, cliquez sur le bouton Test au-dessus du volet de l'outil. L'outil d'entrée s'ouvre dans le simulateur. Saisissez les entrées 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 des outils 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.

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

Code Interpreter : outil first party Google qui combine la génération et l'exécution de code, et 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 en fonction de 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 appelle l'API en votre nom. 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ètres, 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 de l'outil 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 acceptent les types de données suivants : string, number, integer, boolean et array. Le type object n'est pas encore accepté.
Vous ne pouvez pas actuellement 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.

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 ou un jeton d'accès à 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 et 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 et les services Cloud Run se trouvent dans le même projet de ressources, vous n'avez pas besoin d'une autorisation IAM supplémentaire pour les appeler.
- Un jeton d'accès peut être utilisé pour accéder à d'autres API Google Cloud une fois que vous avez accordé les rôles requis à service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
Authentification du compte de service
- Les comptes de service peuvent être utilisés pour authentifier les requêtes de l'outil auprès de toutes les API Google compatibles. 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.
- Pour utiliser cette fonctionnalité, vous devez disposer des autorisations suivantes:
  - roles/iam.serviceAccountUser à l'utilisateur qui crée ou met à jour l'outil pour utiliser l'authentification par compte de service.
  - roles/iam.serviceAccountTokenCreator à l'agent de service Dialogflow.
- Si vous essayez d'utiliser des comptes de service dans plusieurs projets, assurez-vous que votre règle d'administration le permet. Les deux autorisations doivent être accordées dans le projet contenant le compte de service.
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.
OAuth
- Le flux d'identifiants client OAuth est compatible avec l'authentification de serveur à serveur:
  - Ce flux peut être utilisé si la console de l'outil de création d'agents est le propriétaire de la ressource et qu'aucune autorisation de l'utilisateur final n'est requise.
  - L'ID client, le secret client et le point de terminaison du jeton du fournisseur OAuth doivent être configurés dans Dialogflow.
    - Nous vous recommandons de fournir votre secret client à l'aide de Secret Manager.
  - Dialogflow échange un jeton d'accès OAuth auprès du fournisseur OAuth et le transmet dans l'en-tête d'autorisation 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 ensuite:
    
    a. Utilisez l'option d'authentification par jeton porteur 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 l'appeler vous-même côté client et transmettre le résultat de l'appel de l'outil à Dialogflow.
Jeton de support
- Vous pouvez configurer l'authentification par jeton porteur pour transmettre dynamiquement le jeton porteur à partir du client. Ce jeton est inclus dans l'en-tête d'autorisation de la requête.
- Lorsque vous configurez l'authentification de l'outil, vous pouvez désigner un paramètre de session pour qu'il agisse en tant que jeton porteur. Par exemple, utilisez $session.params.<parameter-name-for-token> pour spécifier le jeton.
- Au moment de l'exécution, attribuez le jeton porteur 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 le récupérer à partir d'un paramètre de session, nous vous recommandons de fournir votre jeton à l'aide de Secret Manager.
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. 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 de l'authentification TLS mutuelle pour tous les outils et webhooks.
Certificat CA personnalisé
- Consultez la documentation sur les certificats de certification autorité de certification personnalisés.

Authentification Secret Manager

Si vous utilisez OAuth, une clé API ou un jeton porteur, 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 au Agent de service Dialogflow le rôle Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) pour le nouveau secret.
Copiez vos identifiants dans le presse-papiers.
Ajoutez une nouvelle version de secret à votre secret. Collez vos identifiants en tant que valeur du secret.
- Omettre 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 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 porteur, sélectionnez Jeton porteur comme Type d'authentification, puis cliquez sur Version secrète sous Jeton porteur. 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 en utilisant le 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 fournies 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 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 Open API permet de spécifier des valeurs par défaut. Les valeurs par défaut ne sont utilisées que si aucune valeur d'entrée générée par le LLM ou aucune valeur d'entrée basée sur le paramètre de session n'est définie 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 n'est pas spécifiée.

Outils de datastore

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

Outils de connecteur

Un agent peut utiliser les outils de connecteur pour effectuer des actions à l'aide de vos connexions configurées dans Connecteurs d'intégration. 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 seule connexion afin de regrouper différentes actions que votre agent pourra utiliser.

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

Des 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 accédez alors à la création de connecteurs d'intégration avec un certain nombre de champs préremplis.

Vous pouvez également accéder aux connecteurs d'intégration 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 la section Entités, opérations et actions):

Opérations CRUD d'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 "Order" ou "Case").

Vous pouvez effectuer des opérations CRUD sur chaque entité:
- Créer: crée une entité avec les valeurs de champ spécifiées.
- List (Liste) : recherche basée sur des filtres d'instances d'entités
- Mise à jour: méthode basée sur un filtre pour modifier les valeurs des champs d'entité
- Supprimer: supprime une entité.
- Get récupère une seule entité à l'aide de 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 acceptent 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 cette liste pour connaître les connecteurs compatibles.

Les actions supplémentaires varient 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 pour l'action de votre outil de connecteur, vous pouvez limiter la complexité de ces actions pour l'agent.

Par exemple, si vous ne devez créer qu'une entité avec un sous-ensemble de ses champs, configurer 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 jeton 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 forcement 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 à utiliser pour l'authentification lorsque les actions de l'outil seront appelées.

Outils de fonction

Si une fonctionnalité est accessible par votre code client, mais pas 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 mise en veille 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 datastore peuvent être exécutés côté client en appliquant un forçage d'API lors de l'interaction avec la session.

Exemple :

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