À l'aide d'outils, vous pouvez connecter des applications d'agent à des systèmes externes. Ces systèmes peuvent améliorer les connaissances des applications agents et leur permettre 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.
Limites
Les limites suivantes s'appliquent :
- Vous devez créer un data store (ou connecter un data store existant) lorsque vous créez un outil de data store pour une application d'agent.
- Les applications utilisant à la fois des magasins de données fragmentés et non fragmentés ne sont pas compatibles.
Outils intégrés
Les outils intégrés sont hébergés par Google. Vous pouvez activer ces outils dans les applications d'agent sans configuration manuelle.
Voici les outils intégrés pris en charge:
Code Interpreter: outil Google propriétaire qui combine la capacité de générer et d'exécuter du code, et qui permet à l'utilisateur d'effectuer diverses tâches, y compris l'analyse et la visualisation des 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 pour répondre à 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 en fournissant le schéma OpenAPI. Par défaut, l'application de l'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 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 est 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,queryetheader. Le type de paramètrecookien'est pas encore accepté. - Les paramètres définis par le schéma OpenAPI acceptent les types de données suivants :
string,number,integer,booleanetarray. Le typeobjectn'est pas encore compatible. - 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.
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 à Cloud Functions et aux services Cloud Run une fois que vous avez attribué les rôles roles/cloudfunctions.invoker et roles/run.invoker à 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 ressource, 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 attribué les rôles requis à service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
- 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 la transmette dans la requête.
- OAuth
- 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 doivent être configurés dans Dialogflow. Dialogflow échange un jeton d'accès OAuth et le transmet dans l'en-tête auth de la requête.
- Pour les autres flux OAuth, vous devez utiliser l'outil de fonction pour intégrer votre propre interface utilisateur de connexion afin d'échanger le jeton.
Jeton de support
- Vous pouvez configurer l'authentification de support pour transmettre dynamiquement le jeton de support du client. Ce jeton est inclus dans l'en-tête auth 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> } } ... }Authentification TLS mutuelle
- Consultez la documentation sur l'authentification TLS mutuelle.
Certificat CA personnalisé
- Consultez la documentation sur les certificats CA personnalisés.
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 afin de 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 de l'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
Accordez au compte de service Agent de service Dialogflow les rôles IAM suivants:servicedirectory.viewerdu projet de l'Annuaire des servicesservicedirectory.pscAuthorizedServicedu projet réseau
Lors de la création de l'outil, fournissez le service d'annuaire des services ainsi que le schéma OpenAPI et les informations d'authentification facultatives.
Outils de data store
Une application agent peut utiliser les outils de datastore pour obtenir des réponses aux questions de l'utilisateur final dans vos magasins de données. Vous pouvez configurer un data store de chaque type par outil. L'outil interrogera chacun de ces datastores afin d'obtenir des réponses. Par défaut, l'application agent appelle l'outil de data store en votre nom. Vous pouvez également exécuter les outils de data store côté client.
Le type de data store peut être l'un des suivants:
PUBLIC_WEB: data store qui inclut 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ée pour générer la réponse. L'application de l'agent peut fournir des instructions supplémentaires sur la manière de traiter la réponse provenant des datastores ou sur la manière de répondre en l'absence de réponse.
Vous pouvez remplacer une réponse en ajoutant une entrée de FAQ pour une question spécifique.
Vous pouvez utiliser des exemples pour améliorer davantage le comportement de l'application de l'agent. L'exemple doit comporter 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, vous pouvez utiliser le lien Tools (Outils) dans le panneau 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, deux paramètres facultatifs sont disponibles, avec la chaîne query requise : une chaîne filter et un objet structuré userMetadata.
Le paramètre filter permet de filtrer les requêtes de recherche de vos données structurées ou de données non structurées à l'aide de métadonnées. Cette chaîne doit respecter la syntaxe d'expression de filtre compatible pour les datastores.
Il est recommandé d'utiliser plusieurs exemples et exemples détaillés pour indiquer au LLM de l'agent comment renseigner ce paramètre. Dans le cas d'une chaîne de filtre non valide, le filtre est ignoré lors de l'exécution de la requête de recherche.
Voici un exemple de chaîne filter permettant d'affiner les résultats de recherche en fonction de la localisation:
"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 peut y avoir un champ
mealavec "petit-déjeuner", "déjeuner" et "dîner" comme valeurs valides, et un champservingSizepouvant être n'importe quel entier compris entre 0 et 5. Les instructions peuvent se présenter comme suit: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 l'empêcher potentiellement de répondre à l'utilisateur avec 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 de ce cas.
Le paramètre userMetadata fournit des informations sur l'utilisateur final. Toutes les paires clé/valeur peuvent être renseignées dans ce paramètre. Ces métadonnées sont transmises à l'outil de data store pour mieux renseigner les résultats de recherche et la réponse de l'outil. Nous vous encourageons à fournir plusieurs exemples pour indiquer au LLM de l'agent comment renseigner ce paramètre.
Voici un exemple de valeur de paramètre userMetadata permettant d'affiner les résultats de recherche pertinents pour un utilisateur spécifique:
"userMetadata": {
"favoriteColor": "blue",
...
}
Si, lors des tests, vous constatez que certaines réponses ne répondent pas à vos attentes, les personnalisations suivantes sont disponibles sur la page "Outil" d'un outil de data store:
Fondement de la confiance
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 la confiance que toutes les informations contenues dans la réponse sont compatibles avec les informations stockées dans les data stores. Vous pouvez personnaliser les réponses à autoriser en sélectionnant le niveau de confiance le plus bas qui vous convient. Seules les réponses égales ou supérieures à ce niveau de confiance seront affichées.
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 la requête de générative de résumé. Si aucune option n'est sélectionnée, une option de modèle par défaut est utilisée. Le tableau suivant contient les options disponibles:
| Identifiant du modèle | Langues acceptées |
|---|---|
| text-bison@001 | Disponible dans toutes les langues acceptées. |
| text-bison@002 | Disponible dans toutes les langues acceptées. |
| text-bison@001 ajusté (conversationnel) | Seul l'anglais est accepté pour le moment. |
| text-bison@001 ajusté (informatif) | Seul l'anglais est accepté pour le moment. |
| gémeaux-pro | 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 pouvant 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 sera 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 utilisateur d'origine dans un format plus précis.$sources: l'agent utilise Enterprise Search pour rechercher des sources 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$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 invite personnalisée doit indiquer au LLM de renvoyer "NOT_ENOUGH_INFORMATION" lorsqu'il ne peut pas fournir de réponse. L'agent transformera cette constante en un message convivial pour l'utilisateur.
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. Ceux-ci sont configurés au niveau de l'agent et utilisés à la fois par les LLM de l'agent et par les outils de data store. Si la réponse générée ou certaines parties de l'invite LLM, telles que les entrées de l'utilisateur, contiennent l'une des expressions interdites, cette réponse ne sera pas affichée.
Outils de fonction
Si des fonctionnalités sont accessibles via le code client, mais pas via les outils OpenAPI, vous pouvez utiliser des outils fonction. Les outils de fonction sont toujours exécutés côté client, et non par l'application de l'agent.
Le processus est le suivant :
- Votre code client envoie une requête de détection d'intent.
- L'application de 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 sous forme d'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 de détection d'intent initiales à 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 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
}
}
...
}
Le processus est le suivant :
- Votre code client envoie une requête de détection d'intent qui spécifie l'exécution du client.
- L'application de l'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.
- 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 sous forme d'arguments de sortie.