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.
Limites
Les limites suivantes s'appliquent :
- Vous devez créer un data store (ou en associer un existant) lorsque vous créez un outil de data store pour un agent.
- Les applications avec des datastores par blocs et non par blocs ne sont pas acceptées.
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,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 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 après avoir accordé 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 transmette la clé API dans la requête.
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.
- 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:
- Vous devrez implémenter votre propre UI de connexion et obtenir le jeton d'accès côté client.
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. - Lors de l'exécution, attribuez le jeton porteur 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.
- 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.
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
servicedirectory.viewerdu projet de l'Annuaire des servicesservicedirectory.pscAuthorizedServicedu 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
Un agent peut utiliser des outils de data store pour trouver des réponses aux questions des utilisateurs finaux à partir de vos data stores. Vous pouvez configurer un data store de chaque type par outil. L'outil interrogera chacun de ces entrepôts de données pour obtenir des réponses. Par défaut, l'agent appelle l'outil de data store en votre nom. Vous pouvez également exécuter des outils de data store côté client.
Le type de data store peut être l'un des suivants:
PUBLIC_WEB: data store contenant du contenu Web public.UNSTRUCTURED: data store 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 faire référence à 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'agent peut également fournir des instructions sur la marche à suivre avec la réponse des magasins de données ou sur la façon de répondre en l'absence de réponse.
Vous pouvez remplacer une réponse en ajoutant une entrée de questions fréquentes pour une question spécifique.
Vous pouvez utiliser des exemples pour améliorer davantage le comportement 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 le connecter à votre application, vous pouvez utiliser le lien 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
Lorsque vous créez des exemples d'outils de data store, le paramètre d'entrée de l'outil requestBody fournit trois entrées facultatives avec 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 de vos données structurées ou non structurées avec des métadonnées. Cette chaîne doit respecter la syntaxe d'expression de filtre compatible pour les magasins de données.
Nous vous recommandons d'utiliser plusieurs exemples détaillés pour indiquer au LLM du playbook comment renseigner ce paramètre. En cas de chaîne de filtre non valide, le filtre sera 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 zone géographique:
"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 le playbook 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 un menu, vous pouvez utiliser un champ
mealavec les valeurs valides "petit-déjeuner", "déjeuner" et "dîner", ainsi qu'un champservingSizepouvant être un entier compris entre 0 et 5. Vos 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 le playbook est destiné à une audience d'utilisateurs externes, il peut être nécessaire d'ajouter des instructions pour empêcher le playbook 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 est également utile de fournir un exemple de ce cas.
Le paramètre userMetadata fournit des informations sur l'utilisateur final. Vous pouvez renseigner n'importe quelle paire clé-valeur dans ce paramètre. Ces métadonnées sont transmises à l'outil de data store pour mieux informer les résultats de recherche et la réponse de l'outil. Nous vous recommandons de fournir plusieurs exemples pour indiquer au LLM du playbook comment renseigner ce paramètre.
Voici un exemple de valeur de paramètre userMetadata pour 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 fournir si aucune réponse récapitulative valide n'est disponible pour la requête. Vous pouvez fournir plusieurs exemples pour indiquer au LLM du playbook comment renseigner le remplacement pour les entrées utilisateur liées à différents sujets. Aucun extrait ne sera également généré 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 ne répondent pas à vos attentes lors des tests, les personnalisations suivantes sont disponibles sur la page de l'outil pour un outil de data store:
Ancrer la confiance
Pour chaque réponse générée à partir du contenu de vos datastores connectés, le playbook évalue un niveau de confiance, qui évalue la confiance que toutes les informations de la réponse sont étayées par les informations des datastores. Vous pouvez personnaliser les réponses autorisées en sélectionnant le niveau de confiance le plus bas qui vous convient. Seules les réponses ayant atteint ce niveau de confiance ou supérieur s'affichent.
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 gestionnaire de data store pour la requête générative de résumé. Si aucun n'est sélectionné, 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@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 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: le playbook utilise un module de réécriture pour réécrire la requête utilisateur d'origine dans un format plus précis.$sources: le playbook 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 second source$end-user-metadata: les informations sur l'utilisateur qui envoie 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. Le playbook transformera cette constante en message convivial pour l'utilisateur.
Paramètres de la charge utile
Les paramètres de la charge utile permettent d'ajouter les extraits de data store en tant que contenu enrichi dans la charge utile de la réponse qui est affichée dans le messager.
Phrases interdites (configuration au niveau du playbook)
Vous pouvez définir des expressions spécifiques qui ne doivent pas être autorisées. Ils sont configurés au niveau du playbook et utilisés à la fois par les LLM du playbook et les outils de data store. Si la réponse générée ou des parties de l'invite du LLM, telles que les entrées de l'utilisateur, contiennent l'une des expressions interdites telles quelles, cette réponse ne s'affiche pas.
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 data store 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
}
}
...
}
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'agent détecte qu'un outil est nécessaire, 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.