Gestionnaires d'état

Les gestionnaires d'état, également appelés gestionnaires, permettent de contrôler la conversation en créant des réponses pour les utilisateurs finaux et/ou en remplaçant la page active. À chaque tour de conversation, les gestionnaires sont évaluées et peuvent affecter la session. Les gestionnaires ont trois types généraux de données :

Terme Définition
Exigences des gestionnaires Il s'agit des exigences qui doivent être satisfaites pour que le gestionnaire ait un effet sur la session. Un gestionnaire est appelé lorsqu'il répond à ses exigences et affecte la session d'une manière ou d'une autre.
Fulfillment du gestionnaire Si un gestionnaire est appelé, un fulfillment facultatif est utilisé pour créer des réponses pour les utilisateurs finaux. Ces réponses sont définies dans les données de l'agent statique ou extraites de manière dynamique à partir de votre service de webhook.
Cible de transition du gestionnaire Si un gestionnaire est appelé, une cible de transition facultative est utilisée pour modifier la page actuelle. La page suivante ne peut être qu'une page d'accueil de flux ou une page du flux actuellement actif.

Il existe deux types de gestionnaires d'état avec des exigences de gestionnaire différentes :

Terme Définition
Routes Les routes sont appelées lorsqu'une entrée de l'utilisateur final correspond à un intent et/ou une condition sur l'état de la session est rempli. Une route avec une exigence d'intent est également appelée route d'intent. Une route ne comportant qu'une exigence requise est également appelée route de condition.
Gestionnaires d'événements Les gestionnaires d'événements sont appelés lorsqu'un événement est appelé. Certains événements intégrés sont déclenchés lorsque des entrées de l'utilisateur final inattendues sont reçues ou lorsqu'une erreur de webhook se produit. Vous pouvez également définir des événements personnalisés que vous appelez lorsqu'un événement se produit en dehors de la conversation.

Le traitement d'un gestionnaire d'état comprend trois étapes :

Terme Définition
1. Portée Un gestionnaire doit figurer dans la portée pour avoir un effet sur la session. La portée est déterminée par l'application d'un gestionnaire à un paramètre de flux, de page ou de formulaire, et si le flux ou la page associés sont actifs ou si l'agent tente actuellement de remplir le paramètre de formulaire associé.
2. Évaluation Chaque gestionnaire dans la portée est évalué dans l'ordre. Si les exigences du gestionnaire sont remplies, il réussit l'évaluation.
3. Appel Si un gestionnaire est dans la portée et réussit l'évaluation, il est appelé. Un fulfillment associé est appelé, et toute cible de transition associée est appliquée à la session.

Portée

Pour qu'un gestionnaire soit évalué, il doit être dans la portée. La portée du gestionnaire est un outil important et puissant qui vous aide à contrôler la conversation. En définissant la portée d'un gestionnaire, vous pouvez contrôler :

X Élément
Quand un intent peut être mis en correspondance.
Quand une condition doit être vérifiée.
Quand un événement peut être géré.
Quand une transition de page peut se produire.
Quand est fournie une réponse de fulfillment statique.
Quand un fulfillment compatible avec le webhook est appelé pour des réponses dynamiques.

La portée est déterminée par l'application d'un gestionnaire à un paramètre de flux, de page ou de formulaire, et si le flux ou la page associés sont actifs ou si l'agent tente actuellement de remplir le paramètre de formulaire associé.

Les règles détaillées de champ d'application sont les suivantes :

  • Routes appliquées au flux actif :
    • Si la page actuelle est la page d'accueil du flux, elles sont couvertes.
    • Si la page actuelle ne correspond pas à la page de démarrage du flux, elles n'entrent dans le champ d'application que si elles possèdent des exigences d'intent.
  • Les routes appliquées à la page actuelle sont dans la portée.
  • Les gestionnaires d'événements auxquels le flux actif sont couverts.
  • Les gestionnaires d'événements appliqués à la page actuelle entrent dans le champ d'application.
  • Les gestionnaires d'événements appliqués à un paramètre de formulaire que l'agent tente actuellement de remplir sont couverts.

Routes

Les routes ont deux exigences, et une ou les deux doivent être fournies. Si les deux exigences sont fournies, elles doivent toutes deux être satisfaites pour appeler la route :

Terme Définition
Exigence d'intent Un intent qui doit correspondre à l'entrée de l'utilisateur final pour le tour de conversation actuel Lorsqu'une route possède une exigence d'intent, elle est appelée route d'intent.
Condition requise Une condition qui doit être remplie. Lorsqu'une route présente des exigences préalables, elle est appelée route de condition.

Vous pouvez appliquer des routes à des flux (routes au niveau du flux) et aux pages (routes au niveau de la page). Par exemple, vous pouvez utiliser des routes dans les cas suivants :

X Élément
Lorsque l'entrée de l'utilisateur final correspond à un intent, la correspondance doit déclencher une réponse de fulfillment statique.
Lorsque l'entrée de l'utilisateur final correspond à un intent, la correspondance doit déclencher un fulfillment compatible avec un webhook pour une réponse dynamique.
Lorsque l'entrée de l'utilisateur final a fourni le dernier paramètre de formulaire requis, une vérification de condition déclenche une transition de session vers une autre page.
Lorsque l'entrée de l'utilisateur final a fourni un paramètre de formulaire spécifique, une vérification de condition déclenche une réponse de fulfillment statique.
Une vérification de condition définie sur true force la transition d'une page.

Propagation de l'intent

Normalement, lorsqu'une route est appelée en raison d'un intent correspondant, l'intent est consommé. Un intent utilisé ne peut pas être mis en correspondance, sauf si une nouvelle entrées de l'utilisateur final déclenche une nouvelle correspondance d'intent. Toutefois, il est possible de propager une correspondance d'intent d'un flux à un autre dans le scénario suivant :

  • Une route dans flow F1 a intent I1 comme exigence et flow F2 comme cible de transition.
  • Flow F2 a une route qui a également intent I1 comme exigence.

Dans ce cas, lorsque la route dans flow F1 est appelée, intent I1 est mis en correspondance deux fois pour une entrée d'utilisateur final unique et les deux routes sont appelées.

La propagation des intents est utile dans les scénarios suivants :

X Élément
Remplacez la page actuelle par une page spécifique dans un autre flux (la route du flux cible de transition a une page cible de transition spécifique).
Créez un message d'entrée pour la page de démarrage d'un flux (la route du flux cible de transition a un fulfillment).

Groupes de routes

Lorsque vous créez un agent, vous pouvez constater que de nombreuses pages ont un ensemble commun de routes. Pour rendre les routes réutilisables, vous pouvez définir des groupes de routes. Ces groupes constituent une ressource pour l'intégralité du flux.

Par exemple, vous souhaitez que votre flux gère les entrées de l'utilisateur final, telles que "Je veux ajouter un supplément à ma pizza" et "Je veux modifier la taille de ma boisson". Ces entrées doivent être gérées lorsqu'une des pages du flux est active. Vous pouvez définir deux routes avec des intents afin de gérer ces entrées pour toutes les pages pertinentes, mais cela représente beaucoup de travail en double. Vous pouvez définir le groupe de routes une seule fois et ajouter une référence au groupe sur toutes les pages pertinentes.

Routes au niveau du flux

Les routes au niveau du flux sont des routes appliquées à un flux. Ces types de gestionnaires présentent les cas d'utilisation suivants :

X Élément
Gestionnaires avec une exigence d'intent ou de condition pour la page d'accueil du flux
Gestionnaires avec une exigence d'intent sur la portée pour toutes les pages du flux.

Routes au niveau de la page

Les routes au niveau de la page sont des routes qui sont appliquées à une page. Ces types de gestionnaires présentent les cas d'utilisation suivants :

X Élément
Gestionnaires avec une exigence d'intent ou de condition dans la portée lorsque des pages spécifiques sont actives.

Gestionnaires d'événements

Les gestionnaires d'événements ont besoin d'une exigence pour être appelés :

Terme Définition
Exigence sur l'événement Un événement qui doit être appelé. Les événements sont identifiés par leur nom. Certains événements intégrés sont appelés lorsque des entrées de l'utilisateur final inattendues sont reçues ou lorsqu'une erreur de webhook se produit. Vous pouvez également définir des événements personnalisés que vous appelez lorsqu'un événement se produit en dehors de la conversation.

Vous pouvez appliquer des gestionnaires d'événements aux flux (gestionnaires d'événements au niveau du flux), aux pages (gestionnaires d'événements au niveau de la page) et aux paramètres (gestionnaires d'événements au niveau des paramètres). Par exemple, vous pouvez utiliser des gestionnaires d'événements dans les situations suivantes :

X Élément
Lorsque l'entrée de l'utilisateur final ne correspond à aucun intent, un gestionnaire d'événements sans correspondance fournit une réponse de fulfillment statique spécifique.
Un minuteur expire dans votre système, et vous souhaitez fournir des informations de rappel à l'utilisateur final avec une réponse de fulfillment statique spécifique.

Gestionnaires d'événements au niveau du flux

Les gestionnaires d'événements au niveau du flux sont des gestionnaires d'événements appliqués à un flux. Ces types de gestionnaires présentent les cas d'utilisation suivants :

X Élément
Gestionnaires avec une exigence d'événement dans la portée de la page d'accueil du flux.
Gestionnaires avec une exigence d'événement dans la portée pour toutes les pages du flux.
Gestion des entrées inattendues de l'utilisateur final, partagées par toutes les pages d'un flux
Gestion des erreurs de webhook, partagées par toutes les pages d'un flux
Gestion des événements personnalisés appelés par votre système et partagés par toutes les pages d'un flux

Chaque flux dispose de gestionnaires d'événements pour les événements intégrés no-match et no-input. Ces gestionnaires d'événements sont automatiquement créés lorsque vous créez un flux et ne peuvent pas être supprimés.

Gestionnaires d'événements au niveau de la page

Les gestionnaires d'événements au niveau de la page sont des gestionnaires d'événements appliqués à une page. Ces types de gestionnaires présentent les cas d'utilisation suivants :

X Élément
Gestionnaires avec une exigence d'événements dans la portée lorsque des pages spécifiques sont actives.
Gestion des entrées inattendues de l'utilisateur final, spécifiques à une page
Gestion des erreurs du webhook, spécifique à une page
Gestion des événements personnalisés appelés par votre système, spécifiques à une page

Gestionnaires d'événements au niveau du paramètre

Les gestionnaires d'événements au niveau des paramètres sont des gestionnaires d'événements appliqués à un paramètre de formulaire. Ils sont également appelés gestionnaires de nouvelles invites. Ces gestionnaires d'événements n'autorisent pas les événements personnalisés, car ils sont spécifiquement destinés à gérer les entrées de l'utilisateur final non valides lors du remplissage du formulaire.

Ces types de gestionnaires présentent les cas d'utilisation suivants :

X Élément
L'utilisateur final n'a pas fourni d'entrée valide lorsqu'il a été invité à renseigner un paramètre de formulaire.

Événements intégrés

Les événements suivants sont intégrés. Certains événements sont limités à certains niveaux.

Nom de l'événement
Au niveau du flux Au niveau de la page Au niveau du paramètre Appelé lorsque
sys.no-match-default L'entrée de l'utilisateur final ne correspond à aucun intent pour les gestionnaires dans la portée et ne satisfait à aucun paramètre de formulaire.
sys.no-match-[1-6] Si vous fournissez des gestionnaires pour l'un de ces événements triés par ordre numérique, ils sont appelés à la place de sys.no-match-default et dans l'ordre suivants : sys.no-match-1, sys.no-match-2, ...
sys.no-input-default L'entrée de l'utilisateur final n'a pas été reçue.
sys.no-input-[1-6] Si vous fournissez des gestionnaires pour l'un de ces événements triés par ordre numérique, ils sont appelés à la place de sys.no-input-default et dans l'ordre suivants : sys.no-input-1, sys.no-input-2, ...
sys.invalid-parameter Appelé lorsqu'un webhook invalide le paramètre.
webhook.error L'appel du webhook a renvoyé une erreur.
webhook.error.timeout L'appel du webhook a expiré.

Événements personnalisés

Vous pouvez créer des événements et des gestionnaires d'événements personnalisés. Les événements sont simplement identifiés par un nom. Vous devez éviter d'utiliser des noms d'événements commençant par sys. ou webhook. pour éviter tout conflit avec les événements intégrés.

Pour appeler un événement avec l'API, consultez le champ queryInput.event de la méthode detectIntent pour le type Session.

Sélectionnez un protocole et une version pour la référence de session :

Protocole V3beta1
REST Ressource de session
RPC Interface de session
Java SessionsClient
Node.js SessionsClient
Python SessionsClient

Ordre d'évaluation

Les gestionnaires sont évalués dans un ordre spécifique. Les règles générales suivantes s'appliquent :

  1. Seuls les gestionnaires dans la portée sont évalués.
  2. Seuls les gestionnaires dont les exigences sont satisfaites peuvent être appelés.
  3. Si un gestionnaire sans cible de transition est appelé, l'évaluation de la liste des gestionnaires se poursuit. En raison de cette règle, plusieurs fulfillments peuvent ajouter plusieurs messages à la file d'attente de réponses.
  4. Si un gestionnaire avec une cible de transition est appelé, l'évaluation de la liste des gestionnaires se termine.
  5. Si un gestionnaire avec le fulfillment est appelé et que le fulfillment génère une erreur webhook :
    • Si un gestionnaire d'événements relève de la portée de l'événement, il gère l'événement et l'évaluation de la liste des gestionnaires.
    • Si aucun gestionnaire d'événements n'est dans le champ d'application de l'événement, le webhook échoue silencieusement.
  6. Lorsqu'une exigence d'intent ou de condition est remplie, l'intent ou la condition n'est pas consommé. Par conséquent, plusieurs routes ayant le même intent ou la même condition peuvent être appelées.
  7. Lorsqu'une exigence d'événement est satisfaite, l'événement est consommé. Ainsi, seul le premier gestionnaire d'événements trouvé pour l'événement peut être appelé.

L'évaluation comporte trois phases :

  1. Les routes présentant une exigence d'intent sont évaluées dans l'ordre suivant :
    1. Au niveau de la page : routes individuelles appliquées à la page actuelle, dans l'ordre indiqué.
    2. Groupes au niveau de la page : groupes de routes appliqués à la page active, dans l'ordre indiqué.
    3. Au niveau du flux : routes appliquées au flux actif, dans l'ordre indiqué.
  2. Les routes avec seulement une exigence de condition sont évaluées dans l'ordre suivant :
    1. Au niveau de la page : routes individuelles appliquées à la page actuelle, dans l'ordre indiqué.
  3. Les gestionnaires d'événements sont évalués dans l'ordre suivant :
    1. Au niveau du paramètre : gestionnaires d'événements appliqués au paramètre de formulaire de la page actuelle que l'agent tente de remplir (gestionnaires de nouvelles), dans l'ordre indiqué
    2. Au niveau de la page : gestionnaires d'événements appliqués à la page active, dans l'ordre indiqué
    3. Au niveau du flux : gestionnaires d'événements appliqués au flux actif, dans l'ordre indiqué

Cibles de transition symboliques

Lorsque vous saisissez une cible de transition pour un gestionnaire, vous pouvez entrer des flux ou des pages spécifiques, mais vous pouvez également saisir des cibles de transition symboliques :

Cible de transition symbolique
Description
START_PAGE Passe à la page de démarrage du flux actif portant le même nom
END_FLOW Termine le flux actuellement actif et revient à la page qui a provoqué une transition vers le flux actuel
END_SESSION Effacez la session en cours et passez à la page spéciale nommée END_SESSION. La prochaine entrée utilisateur redémarrera la session sur la page de d'accueil du flux de démarrage par défaut.
PREVIOUS_PAGE Passe à la page précédente
CURRENT_PAGE Revient à la page actuelle. Cela peut être utile si vous voulez que l'agent répète quelque chose.