À l'aide d'outils, vous pouvez connecter des applications d'agent à des systèmes externes. Ces systèmes peuvent accroître la connaissance 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 agent.
- Les applications comportant à la fois des data stores 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.
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 comment et quand 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 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 pris en charge. - Les paramètres définis par le schéma OpenAPI acceptent les types de données suivants :
string,number,integer,boolean,array. Le typeobjectn'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 disponibles lorsque vous appelez 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 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 attribué les rôles requis à service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com.
- Clé API
- Pour configurer l'authentification par clé API, indiquez 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 d'authentification de la requête.
- Pour les autres flux OAuth, vous devez utiliser l'outil de fonction afin d'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 de manière dynamique le jeton de support à partir 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 agira 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
- 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, ce qui permet de 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é:
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 d'agent de service Dialogflow associé à 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.viewerdu projet de l'Annuaire des servicesservicedirectory.pscAuthorizedServicedu projet réseau
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 l'utilisateur final à partir de vos data stores. Vous pouvez configurer un data store de chaque type pour chaque outil. L'outil interrogera chacun de ces datastores 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 de la source de contenu utilisée pour générer la réponse. L'application agent peut également fournir des instructions sur la façon d'utiliser la réponse fournie par les data stores ou la procédure à suivre en l'absence de réponse.
Vous pouvez écraser une réponse en ajoutant une entrée de FAQ 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, vous pouvez utiliser 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 requise : 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 sur vos données structurées ou les données non structurées à l'aide de métadonnées. Cette chaîne doit suivre la syntaxe d'expression de filtre acceptée 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. Si une chaîne de filtre n'est pas 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 du lieu:
"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 sur le menu, il peut y avoir un champ
mealavec "petit-déjeuner", "déjeuner" et "dîner" comme valeurs valides, et un champservingSizequi 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 éviter qu'il ne réponde à l'utilisateur en lui fournissant 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. 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 informer les résultats de la recherche et la réponse de l'outil. Nous vous recommandons de 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",
...
}
Le paramètre fallback fournit une réponse que l'outil de data store doit utiliser s'il n'existe pas de réponse résumée valide pour la requête. Plusieurs exemples peuvent être fournis pour indiquer au LLM de l'agent comment renseigner la création de remplacement pour les entrées utilisateur liées à différents sujets. Il n'y aura pas non plus d'extraits dans la sortie de l'outil. Cette optimisation peut être utilisée pour réduire la latence et l'utilisation de la limite de 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 au cours des tests ne répondent pas à vos attentes, les personnalisations suivantes sont disponibles sur la page "Outil" d'un outil de data store:
Confiance d'ancrage
Pour chaque réponse générée à partir du contenu de vos datastores connectés, l'agent évalue un niveau de confiance, qui évalue le degré de confiance selon lequel toutes les informations de la réponse sont étayées par les informations présentes dans les datastores. 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 générative de synthèse. Si aucune option n'est sélectionnée, une option de 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 sont 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 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$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'il ne peut pas fournir de réponse. L'agent transforme cette constante en 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 réponse 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. Celles-ci sont configurées au niveau de l'agent et utilisées à la fois par les LLM de l'agent et par les outils du data store. Si la réponse générée ou certaines parties du LLM, telles que les entrées de l'utilisateur, contiennent mot pour mot l'une des expressions interdites, cette réponse ne s'affiche pas.
Outils de fonction
Si des fonctionnalités sont accessibles depuis 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'application agent.
Le processus est le suivant :
- Votre code client envoie une requête de détection d'intent.
- L'application 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 initiale de détection d'intent et la réponse à 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 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 en tant qu'arguments de sortie.