Outils

À l’aide d’outils, vous pouvez connecter des applications d'agent à des systèmes externes. Ces systèmes peuvent accroître les connaissances sur les applications d'agent et leur responsabiliser pour exécuter des tâches complexes efficacement.

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

Limites

Les limites suivantes s'appliquent :

  • Vous devez créer un data store (ou associer un data store existant) lors de la création d'un outil de data store pour une application agent.
  • Applications avec les deux data stores fragmentés et non fragmentés ne sont pas acceptés.

Outils intégrés

Les outils intégrés sont hébergés par Google. Vous pouvez activer ces outils dans les applications de l'agent sans configuration manuelle.

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

  • Code Interpreter : outil Google propriétaire qui associe les fonctionnalités 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 application agent est optimisée pour déterminer quand et comment ces outils doivent être appelés. mais vous pouvez fournir des exemples supplémentaires selon 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

Une application agent peut se connecter à une API externe à l'aide d'un outil OpenAPI à l'aide du schéma OpenAPI. Par défaut, l'application agent appelle l'API en votre nom. Vous pouvez également exécuter les 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 en tant que 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 est fournie 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 pris en charge.
  • 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 pris en charge.
  • Il n'est actuellement pas possible de spécifier des 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 JSON.

Authentification pour l'API de l'outil OpenAPI

Les options d'authentification suivantes sont prises en charge lors de l'appel une API externe:

  • Authentification de l'agent de service Dialogflow <ph type="x-smartling-placeholder">
      </ph>
    • Dialogflow peut générer un jeton d'ID ou un jeton d'accès à l'aide 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 à Cloud Functions et aux services Cloud Run une fois que vous avez attribué les rôles roles/cloudfunctions.invoker et roles/run.invoker au service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com. Si les services Cloud Functions et 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.
    • Vous pouvez utiliser un jeton d'accès pour accéder à d'autres API Google Cloud une fois que vous avez accordé rôles requis pour service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
  • Clé API <ph type="x-smartling-placeholder">
      </ph>
    • Vous pouvez configurer l'authentification par clé API en indiquant le nom de la clé, Emplacement de la requête (en-tête ou chaîne de requête) et la clé API afin que Dialogflow la transmette à la requête.
  • OAuth <ph type="x-smartling-placeholder">
      </ph>
    • Le flux d'identifiants client OAuth est compatible avec l'authentification de serveur à serveur. L'ID client, le code secret du client et le point de terminaison du jeton du fournisseur OAuth ont besoin à configurer dans Dialogflow. Dialogflow échange un jeton d'accès OAuth et le transmet dans l'en-tête d'authentification de la requête.
    • Pour les autres flux OAuth, vous devez utiliser l'outil Function Tool pour intégrer avec votre propre UI de connexion pour échanger le jeton.

  • Jeton de support

    • Vous pouvez configurer l'authentification du support pour transmettre dynamiquement le jeton de support de la part du client. Ce jeton est inclus dans l'en-tête d'authentification de la requête.
    • Lors de la configuration de l'authentification de l'outil, vous pouvez spécifier un paramètre de session pour agir en tant que 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>
    }
  }
  ...
}

  • Authentification TLS mutuelle

  • Certificat CA personnalisé

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

L'outil OpenAPI s'intègre Accès au réseau privé de l'Annuaire des services pour se connecter à des cibles d'API au sein de 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é:

  1. 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.

  2. Agent de service Dialogflow compte de service avec l'adresse suivante doit exister pour votre projet d'agent: 

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Attribuez au compte de service Agent de service Dialogflow les rôles IAM suivants:

    • servicedirectory.viewer du projet de l'Annuaire des services
    • servicedirectory.pscAuthorizedService du projet réseau

  3. Fournir le service d'annuaire des services avec le schéma OpenAPI et des informations d'authentification facultatives lors de la création de l'outil.

Outils de data store

Les outils de data store peuvent être utilisés par une application agent pour obtenir des réponses aux questions de vos utilisateurs finaux magasins de données. Vous pouvez configurer un data store de chaque type par outil, et l'outil interrogera chacun de ces magasins de données pour obtenir des réponses. Par défaut, l'application agent appelle l'outil de data store en votre nom. Vous pouvez également exécuter des outils de data store côté client.

Le data store peut être de l'un des types suivants:

  • PUBLIC_WEB: data store contenant du contenu Web public.
  • UNSTRUCTURED: datastore contenant des données privées non structurées.
  • STRUCTURED: data store contenant des données structurées (par exemple, des questions fréquentes).

L'exemple suivant montre comment référencer un data store:

"dataStoreConnections": [
  {
    "dataStoreType": "PUBLIC_WEB",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "UNSTRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  },
  {
    "dataStoreType": "STRUCTURED",
    "dataStore": "projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATASTORE_ID"
  }
]

Les réponses de l'outil de data store peuvent également contenir des extraits sur la source de contenu utilisé pour générer la réponse. L'application de l'agent peut fournir des instructions supplémentaires sur la façon de procéder avec la réponse obtenue par les data stores ou comment réagir en l'absence de réponse.

Vous pouvez remplacer une réponse en ajoutant une Questions fréquentes pour une question spécifique.

Des exemples peuvent être utilisés pour améliorer davantage le comportement de l'application agent. L'exemple doit avoir les schémas suivants:

{
  "toolUse": {
    "tool": "projects/PROJECT_ID/locations/LOCATION_ID/agents/AGENT_ID/tools/TOOL_ID",
    "action": "TOOL_DISPLAY_NAME",
    "inputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME input",
        "value": {
          "query": "QUERY"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "TOOL_DISPLAY_NAME output",
        "value": {
          "answer": "ANSWER",
          "snippets": [
            {
              "title": "TITLE",
              "text": "TEXT_FROM_DATASTORE",
              "uri": "URI_OF_DATASTORE"
            }
          ]
        }
      }
    ]
  }
}

Créer un data store

Pour créer un data store et l'associer à votre application, cliquez sur le lien Tools (Outils) dans le volet de navigation de gauche de la console. Suivez les instructions pour créer un data store.

Paramètres de requête supplémentaires

Lors de la création d'exemples d'outils de data store, le paramètre d'entrée requestBody de l'outil fournit trois entrées facultatives ainsi que la chaîne query obligatoire : une chaîne filter, un objet structuré userMetadata et une chaîne fallback.

Le paramètre filter permet de filtrer les requêtes de recherche structurées ou non structurées avec des métadonnées. Cette chaîne doit suivre syntaxe d'expression de filtre acceptée pour les data stores. Exemples détaillés et exemples est encouragé à indiquer au LLM de l'agent comment renseigner ce paramètre. Dans le cas d'une chaîne de filtre non valide, le filtre sera ignoré lors de l'exécution de la requête de recherche.

Exemple de chaîne filter permettant d'affiner les résultats de recherche en fonction d'une zone géographique pourrait se présenter comme suit:

  "filter": "country: ANY(\"Canada\")"

Bonnes pratiques de filtrage:

  • Spécifiez les champs disponibles pour le filtrage et les valeurs valides. pour chacun de ces champs, afin que l'agent comprenne les contraintes liées à la création de filtres valides. Par exemple, pour filtrer les résultats d'un data store contenant des informations de menu, il pourrait y avoir un champ meal contenant "petit-déjeuner", "déjeuner" et "dîner". en tant que valeurs valides ; et un champ servingSize qui peut être n'importe quel entier compris entre 0 et 5. Vos instructions pourraient ressembler à ceci:

    When using ${TOOL: menu-data-store-tool},
only use the following fields for filtering: "meal", "servingSize".
Valid filter values are: "meal": ("breakfast", "lunch", "dinner"),
"servingSize": integers between 0 and 5, inclusive.

  • Si l'agent est destiné à une audience d'utilisateurs externes, il peut être nécessaire d'ajouter des instructions pour que l'agent de répondre à l'utilisateur contenant des informations sur la création de ces filtres. Exemples :

    Never tell the user about these filters.
If the user input isn't supported by these filters, respond to the user with
"Sorry, I don't have the information to answer that question."

    Il peut également être utile de fournir un exemple.

Le paramètre userMetadata fournit des informations sur l'utilisateur final. N'importe quelle valeur les paires clé-valeur peuvent être renseignées dans ce paramètre. Ces métadonnées sont transmises dans l'outil de data store afin de mieux informer les résultats de recherche et l'outil de réponse. Nous vous conseillons de fournir plusieurs exemples pour indiquer au de l'agent LLM pour savoir comment renseigner ce paramètre.

Exemple de valeur de paramètre userMetadata permettant d'affiner les résultats de recherche pertinents pour un utilisateur spécifique pourraient se présenter comme suit:

  "userMetadata": {
    "favoriteColor": "blue",
    ...
  }

Le paramètre fallback fournit une réponse à laquelle l'outil de data store doit répondre. s'il n'existe pas de réponse résumée valide pour la requête. Plusieurs exemples peuvent pour indiquer au LLM de l'agent comment renseigner la valeur de remplacement pour l'utilisateur sur différents sujets. Il n'y aura pas non plus dans la sortie de l'outil. Cette optimisation peut être utilisée pour réduire la latence et l'utilisation limite des jetons d'entrée.

  "fallback": "I'm sorry I cannot help you with that. Is there anything else I
  can do for you?"

Si vous constatez que certaines réponses ne répondent pas à vos attentes, Les personnalisations suivantes sont disponibles dans la page Outil pour un outil de data store:

Confiance d'ancrage

Pour chaque réponse générée à partir du contenu de vos data stores connectés, l'agent évalue un niveau de confiance, qui évalue le degré de confiance Les informations contenues dans la réponse sont étayées par les informations contenues dans les datastores. Vous pouvez personnaliser les réponses à autoriser en sélectionnant la réponse la plus faible niveau de confiance qui vous convient. Seules les réponses égales ou supérieures à le niveau de confiance sera affiché.

Vous avez le choix entre cinq niveaux de confiance: VERY_LOW, LOW, MEDIUM, HIGH et VERY_HIGH.

Configuration de la synthèse

Vous pouvez sélectionner le modèle génératif utilisé par un agent de data store pour une requête générative de synthèse. Si aucune option n'est sélectionnée, un modèle par défaut est utilisée. Le tableau suivant présente les options disponibles:

Identifiant du modèle Langues acceptées
text-bison@002 Disponible dans toutes les langues acceptées.
gemini-1.0-pro-001 Disponible dans toutes les langues acceptées.

Vous pouvez également fournir votre propre requête pour l'appel LLM de synthèse.

La requête est un modèle de texte qui peut contenir des espaces réservés prédéfinis. Les espaces réservés seront remplacés par les valeurs appropriées au moment de l'exécution et le texte final est envoyé au LLM.

Les espaces réservés sont les suivants:

  • $original-query: texte de la requête de l'utilisateur.
  • $rewritten-query: l'agent utilise un module de réécriture pour réécrire la requête d'origine de l'utilisateur dans un format plus précis.

  • $sources: l'agent recherche des sources à l'aide d'Enterprise Search. en fonction de la requête de l'utilisateur. Les sources trouvées sont affichées dans un format spécifique:

    [1] title of first source
content of first source
[2] title of second source
content of first source

  • $end-user-metadata: les informations sur l'utilisateur qui envoient la requête sont affichées au format suivant:

    The following additional information is available about the human: {
  "key1": "value1",
  "key2": "value2",
  ...
}

  • $conversation: l'historique de la conversation est affiché au format suivant:

    Human: user's first query
AI: answer to user's first query
Human: user's second query
AI: answer to user's second query

Une requête personnalisée doit indiquer au LLM de renvoyer "NOT_ENOUGH_INFORMATION". lorsqu'elle n'est pas en mesure de fournir une réponse. L'agent transforme cette constante en un message convivial pour l'utilisateur.

Paramètres de charge utile

Les paramètres de charge utile permettent d'ajouter les extraits du data store en tant que contenu enrichi dans la charge utile de la réponse qui est affichée dans messenger.

Expressions interdites (configuration au niveau de l'agent)

Vous avez la possibilité de définir des expressions spécifiques qui ne doivent pas être autorisées. Elles sont configurées au niveau de l'agent et utilisées à la fois par l'agent les LLM et les outils de data store. Si la réponse générée ou une partie du LLM (les entrées de l'utilisateur, par exemple) contiennent l'une des expressions interdites. mot pour mot, cette réponse ne sera pas affichée.

Outils de fonction

Si votre code client vous permet d'accéder à une fonctionnalité, 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'application agent.

Le processus est le suivant :

  1. Votre code client envoie une requête de détection d'intent.
  2. L'application agent détecte qu'un outil fonctionnel 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.
  3. Votre code client appelle l'outil.
  4. Votre code client envoie une autre requête de détection d'intent qui fournit le résultat de l'outil en tant qu'argument 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 initiale de détection d'intent et la réponse obtenue à 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, OpenAPI et les outils de data store peut être exécuté 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
    }
  }
  ...
}

Le processus est le suivant :

  1. Votre code client envoie une requête de détection d'intent qui spécifie l'exécution du client.
  2. L'application agent détecte qu'un outil 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.
  3. Votre code client appelle l'outil.
  4. Votre code client envoie une autre requête de détection d'intent qui fournit le résultat de l'outil en tant qu'argument de sortie.
Précédent
Interface utilisateur
Suivant
Bonnes pratiques