Principes de base de Microsoft Bot Framework

S'APPLIQUE À : SDK v4

Un bot est une application avec laquelle les utilisateurs interagissent par le biais d’une conversation textuelle, graphique (cartes ou images) ou vocale. Azure AI Bot Service est une plateforme cloud. Elle héberge des bots et les met à la disposition des canaux, tels que Microsoft Teams, Facebook ou Slack.

Bot Framework Service, qui est un composant d'Azure AI Bot Service, envoie des informations entre l'application connectée au bot de l'utilisateur et le bot. Chaque canal peut inclure des informations supplémentaires dans les activités qu'ils envoient. Avant de créer des bots, il est important de comprendre comment un bot utilise les objets d'activité pour communiquer avec ses utilisateurs.

Ce diagramme illustre deux types d'activités, la mise à jour de conversation et le message, qui peuvent être échangés lorsqu'un utilisateur communique avec un bot écho.

Bot Framework Service envoie une mise à jour de conversation lorsque quelqu'un rejoint la conversation. Par exemple, au démarrage d'une conversation avec Bot Framework Emulator, vous pourrez voir deux activités de mise à jour de conversation (une pour l'utilisateur rejoignant la conversation et l'autre pour le bot rejoignant la conversation). Pour distinguer ces activités de mise à jour de conversation, vérifiez qui est inclus dans la propriété des membres ajoutés de l'activité.

L'activité message transfère les informations de conversation entre les parties. Dans un exemple de bot d’écho, les activités de message transfèrent du texte simple et le canal rend ce texte. L’activité de message peut également contenir du texte à prononcer, des actions suggérées ou des cartes à afficher.

Conseil

C'est à chaque chaîne de mettre en œuvre le protocole Bot Framework. Cependant, la façon dont chaque chaîne le fait peut être légèrement différente. Par exemple, certains canaux envoient d'abord des activités de mise à jour de conversation, et certains les envoient après avoir envoyé la première activité de message. Un canal peut inclure à la fois le bot et l'utilisateur dans une activité de mise à jour de conversation, tandis qu'un autre peut envoyer deux activités de mise à jour de conversation.

Dans cet exemple, le bot crée et envoie une activité de message en réponse à l’activité de message entrant reçu. Cependant, un bot peut répondre d'une autre manière à une activité de message reçue, et il est courant qu'un bot réponde à une activité de mise à jour de conversation en envoyant une activité de message avec un message de bienvenue. Pour plus d'informations, consultez la rubrique comment accueillir un utilisateur.

Kit de développement logiciel (SDK) Bot Framework

Le kit de développement logiciel (SDK) Bot Framework vous permet de créer des bots qui peuvent être hébergés sur Azure AI Bot Service. Le service définit une API REST et un protocole d'activité pour la façon dont votre bot et vos canaux ou utilisateurs peuvent interagir. Le kit de développement logiciel (SDK) s'appuie sur cette API REST et fournit une abstraction du service afin que vous puissiez vous concentrer sur la logique de conversation. Bien que vous n'ayez pas besoin de comprendre le service REST pour utiliser le kit de développement logiciel (SDK), il peut être utile de comprendre certaines de ses caractéristiques.

Les bots sont des applications qui ont une interface de conversation. Les bots peuvent être utilisés pour faire passer des tâches répétitives et simples, comme la réservation de table ou le recueil d’informations de profil, vers des systèmes automatisés qui ne nécessitent plus d’intervention humaine directe. Les utilisateurs conversent avec le bot à l’aide de texte, de cartes interactives et avec la voix. Une interaction avec un bot peut se composer d’une question-réponse rapide, ou il peut s’agir d’une conversation plus sophistiquée fournissant un accès à des services de manière plus intelligente.

Remarque

La prise en charge des caractéristiques fournies par le kit de développement logiciel (SDK) et l'API REST varient selon la chaîne. Vous pouvez tester votre bot à l'aide de Bot Framework Emulator, mais vous devez également tester toutes les fonctionnalités de votre bot sur chaque chaîne dans laquelle vous envisagez de rendre votre bot disponible.

Les interactions impliquent l'échange d'activités, gérées à leurs tours.

Activités

Chaque interaction entre l'utilisateur (ou une chaîne) et le bot est perçue comme une activité. Le schéma d'activité Bot Framework définit les activités qui peuvent être échangées entre un utilisateur ou une chaîne et un bot. Les activités peuvent correspondre à du texte humain ou à une voix, à des notifications d'application à application, à des réactions à d'autres messages, etc.

Tours

Dans une conversation, les gens parlent un à la fois, tour à tour. En général, un bot réagit à l’entrée utilisateur. Dans le kit SDK Bot Framework, un tour désigne l’activité entrante de l’utilisateur dans le bot et toute activité que le bot renvoie à l’utilisateur comme réponse immédiate. On peut considérer qu'un tour est le traitement associé à la réception par le bot d'une activité donnée.

Par exemple, un utilisateur peut demander à un bot d'effectuer une certaine tâche. Le bot pourrait répondre par une question pour obtenir plus d'informations sur la tâche, ce qui met fin à ce tour. Au tour suivant, le bot reçoit un nouveau message de l'utilisateur qui pourrait contenir la réponse à la question du bot, ou il pourrait représenter un changement d'objet ou une demande d'ignorer la demande initiale pour effectuer la tâche.

Structure d'application de bot

Le kit de développement logiciel (SDK) définit une classe de bot qui gère le raisonnement des conversations de l'application bot. Classe de bot :

• Elle reconnaît et interprète l'entrée de l'utilisateur.
• Elle raisonne relativement à l'entrée et exécute des tâches pertinentes.
• Elle génère des réponses sur l'action en cours du bot ou celle passée.

Le kit de développement logiciel (SDK) définit également une classe d'adaptateur qui gère la connectivité avec les canaux. L'adaptateur :

• Il fournit une méthode pour gérer les demandes provenant des requêtes et les méthodes permettant de générer des requêtes vers la chaîne de l'utilisateur.
• Il inclut un pipeline d'intergiciels, qui introduit le traitement de tour en dehors du gestionnaire de tour de votre bot.
• Il appelle le gestionnaire de tour du bot et intercepte les erreurs qui n'y sont pas gérées.

En outre, les bots doivent souvent récupérer et stocker l'état à chaque tour. L'état est géré par le stockage, l'état du bot, et les classes d'accesseur de la propriété. Le kit de développement logiciel (SDK) ne fournit pas de stockage prédéfini, mais fournit des abstractions pour le stockage et quelques mises en œuvre d'une couche de stockage. La rubrique de l'état de gestion décrit ces caractéristiques de l'état de stockage.

Le kit de développement logiciel (SDK) ne nécessite pas d'utiliser une couche d'application spécifique pour envoyer et recevoir des demandes Web. Bot Framework propose des modèles et des échantillons pour ASP.NET (C#), restify (JavaScript) et aiohttp (Python). Toutefois, vous pouvez choisir d'utiliser une couche d'application différente pour votre application.

Lorsque vous créez un bot à l'aide du kit de développement logiciel (SDK), vous fournissez le code pour recevoir le trafic HTTP et le transférer à l'adaptateur. Bot Framework fournit quelques modèles et exemples que vous pouvez utiliser pour développer vos propres bots.

Remarque

Les kits de développement logiciel (SDK) JavaScript, C# et Python bot Framework continueront d'être pris en charge. Toutefois, le kit de développement logiciel (SDK) Java est mis hors service avec une prise en charge finale à long terme se terminant en novembre 2023. Seuls les correctifs de sécurité et de bogues critiques dans ce référentiel seront appliqués.

Les bots existants créés avec le kit de développement logiciel (SDK) Java continueront de fonctionner.

Pour la nouvelle génération de bots, envisagez d'utiliser Power Virtual Agents et découvrez comment choisir la solution de chatbot appropriée.

Pour plus d'informations, consultez Les futures versions de bot.

Logique du bot

L'objet bot contient le raisonnement de conversations ou la logique d'un tour et expose un gestionnaire de tour, qui est la méthode pouvant accepter les activités entrantes à partir de l'adaptateur de bot.

Le kit de développement logiciel (SDK) fournit deux paradigmes différents pour la gestion de votre logique de bot.

• Les gestionnaires d'activités fournissent un modèle piloté par les événements dans lequel les types d'activité entrants et les sous-types sont les événements. Considérez un gestionnaire d'activités pour les bots qui ont des interactions courtes et limitées avec l'utilisateur.
  • Utilisez un gestionnaire d'activités et mettez en œuvre des gestionnaires pour chaque type d'activité ou sous-type que votre bot reconnaîtra et par lequel il réagira.
  • Utilisez un gestionnaire d'activité Teams pour créer des bots qui peuvent se connecter à la chaîne Teams. (La chaîne Teams nécessite que le bot gère un comportement spécifique dans la chaîne.)
• La bibliothèque de dialogues fournit un modèle axé sur l'état pour gérer une conversation de longue durée avec l'utilisateur.
  • Utilisez un gestionnaire d'activités et une boîte de dialogue de composant pour les conversations en grande partie séquentielles. Pour plus d'informations, consultez les dialogues de composant et de cascade.
• Mettez en œuvre votre propre classe de bot et fournissez votre logique personnelle pour gérer chaque tour. Pour obtenir un exemple, découvrez comment créer vos propres invites pour assembler une entrée utilisateur.

Adaptateur de bot

L'adaptateur a une méthode d'activité de processus pour démarrer un tour.

• Il prend le corps de la demande (la charge utile de la requête, traduite en activité) et l'en-tête de demande en tant qu'arguments.
• Il vérifie si l'en-tête d'authentification est valide.
• Il crée un objet de contexte pour le tour. L'objet de contexte inclut des informations sur l'activité.
• Il envoie l'objet de contexte par son pipeline d'intergiciel.
• Il envoie ensuite l'objet de contexte au gestionnaire de tour de l'objet bot.

De plus, l'adaptateur :

• Met en forme et envoie des activités de réponse. Ces réponses sont généralement des messages pour l'utilisateur, mais peuvent également inclure des informations à consommer directement par la chaîne de l'utilisateur.
• Fait apparaître d'autres méthodes fournies par le connecteur de Bot API REST, telles que la mise à jour du message et la suppression du message.
• Intercepte les erreurs ou les exceptions qui n'ont pas été détectées d'une autre manière pour le tour.

Le contexte du tour

L’objet de contexte de tour fournit des informations sur l’activité, comme l’expéditeur et le destinataire, le canal, et d’autres données nécessaires pour traiter l’activité. Il permet également d’ajouter des informations pendant le tour entre les différentes couches du bot.

Le contexte de tour est l’une des abstractions les plus importantes du SDK. Il transfère non seulement l'activité entrante à tous les composants d'intergiciel et à la logique d'application, mais fournit également le mécanisme par lequel les composants d'intergiciel et la logique de bot peuvent envoyer des activités sortantes.

Middleware

Les intergiciels sont très similaires à n’importe quel autre intergiciel de messagerie, et comprennent un ensemble linéaire de composants qui sont exécutés dans un ordre précis, ce qui donne à chacun une chance d’agir sur l’activité. La dernière étape du pipeline d’intergiciels est un rappel au gestionnaire de tours, sur la classe du bot avec laquelle l’application s’est inscrite auprès de la méthode de traitement d’activité de l’adaptateur. L'intergiciel met en œuvre une méthode d'activation que l'adaptateur appelle.

Le gestionnaire de tours prend un contexte de tours comme argument. En règle générale, la logique d'application exécutée dans la fonction de gestionnaire de tours traite le contenu de l'activité entrante et génère une ou plusieurs activités en réponse, envoyant ces activités sortantes à l'aide de la fonction d'envoi d'activité sur le contexte de tours. Appelez l’envoi d’activité sur le contexte de tour entraîne l’appel des composants des intergiciels sur les activités sortantes. Les composants des intergiciels s'exécutent avant et après la fonction du gestionnaire de tours du bot. L'exécution est intrinsèquement imbriquée ; à ce titre, on la compare parfois à un oignon.

La rubrique intergiciel décrit l'intergiciel en profondeur.

Bot State et Stockage

Comme avec d'autres applications Web, un bot est intrinsèquement sans état. Un état au sein d'un bot suit les mêmes paradigmes que les applications Web modernes et le kit de développement logiciel (SDK) Bot Framework offre une couche de stockage et des abstractions de gestion de l'état pour en faciliter la gestion.

La rubrique de l'état de gestion décrit ces caractéristiques de l'état de stockage.

Point de terminaison de messagerie et approvisionnement

En règle générale, votre application a besoin d'un point de terminaison REST pour recevoir des messages. Elle devra également approvisionner des ressources pour votre bot conformément à la plateforme que vous décidez d'utiliser.

Suivez le guide de démarrage rapide Créer un bot pour créer et tester un bot écho simple.

Détails HTTP

Les activités arrivent dans le bot à partir du service Bot Framework via une requête HTTP POST. Le bot répond à la requête POST entrante avec un code d’état HTTP 200. Les activités sont envoyées du bot au canal dans une requête HTTP POST séparée vers le service Bot Framework. Leur réception génère un code d’état HTTP 200.

Le protocole ne spécifie pas l'ordre dans lequel ces demandes POST et leurs accusés de réception sont transmis. Toutefois, pour s’adapter aux infrastructures de service HTTP courantes, ces demandes sont généralement imbriquées, ce qui signifie que la requête HTTP sortante est effectuée à partir du bot dans le périmètre de la requête HTTP entrante. Ce schéma de fonctionnement est illustré dans le diagramme précédent. Dans la mesure où il existe deux connexions HTTP distinctes à la suite, le modèle de sécurité doit couvrir les deux.

Remarque

Le bot a 15 secondes pour accuser réception de l'appel dans un état 200 sur la plupart des canaux. Si le bot ne répond pas dans les 15 secondes, une erreur HTTP GatewayTimeout (504) apparaitra.

Pile de traitement d’une activité

Reprenons le diagramme de séquence précédent en nous concentrant sur le processus de réception d'un message.

Le chaîne envoie le message de l'utilisateur au service Azure AI Bot Service et le service transfère le message au point de terminaison de messagerie du bot. La réponse du bot est envoyée à l'utilisateur dans l'étendue du tour.

Dans l’exemple ci-dessus, le bot a répondu à l’activité de message avec une autre activité de message contenant le même message texte. Le traitement commence par la requête HTTP POST. Les informations de l’activité sont transportées sous la forme d’une charge JSON arrivant sur le serveur Web. Souvent, ASP.NET projets est utilisé pour les bots C#, et une cadre populaire tel qu'Express ou restify est utilisée pour les bots JavaScript Node.js.

L’adaptateur, un composant intégré du Kit de développement logiciel (SDK), est l’élément central du runtime du Kit de développement logiciel (SDK). L’activité est transmise sous forme de code JSON dans le corps HTTP POST. Ce code JSON est désérialisé pour créer l'objet activité qui est ensuite transmis à l'adaptateur par le biais de sa méthode de traitement de l'activité. Lors de la réception de l’activité, l’adaptateur crée un contexte de tour et appelle l’intergiciel.

Comme mentionné ci-dessus, le contexte de tour fournit le mécanisme pour permettre au bot d’envoyer des activités sortantes, le plus souvent en réponse à une activité entrante. Le contexte de tour fournit des méthodes de réponses envoi, mise à jour et suppression des activités. Chaque méthode de réponse s’exécute dans un processus asynchrone.

Important

La conversation qui traite le tour de bot principal se charge de supprimer l'objet de contexte quand il prend fin. Veillez à exécuter une opération await sur tous les appels d’activité, afin que le thread principal attende l’activité générée avant de terminer son traitement et de supprimer le contexte de tour. Sinon, si une réponse (et ses gestionnaires) prend un certain temps et essaie d’agir sur l’objet de contexte, elle risque de recevoir une erreur de type contexte supprimé.

Modèles de bot

Vous devez choisir l'utilisation de la couche d'application pour votre application. Toutefois, Bot Framework a des modèles et des exemples pour ASP.NET (C#), restify (JavaScript) et aiohttp (Python). La documentation est écrite en supposant que vous utilisez l'une de ces plateformes, mais que le kit de développement logiciel (SDK) n'en a pas besoin. Consultez le guide de démarrage rapide Créer un bot pour obtenir des instructions sur l'accès et l'installation des modèles.

Un bot est une application Web, et des modèles sous fournis pour chaque version de langage du kit de développement logiciel (SDK). Tous les modèles fournissent une mise en œuvre et un adaptateur de point de terminaison par défaut. Chaque modèle inclut les éléments suivants :

• Provisionnement des ressources
• Une mise en œuvre du point de terminaison HTTP spécifique à une langue qui achemine les activités entrantes vers un adaptateur.
• Un objet adaptateur.
• Un objet de bot

La principale différence entre les différents types de modèles se trouve dans l'objet de bot. Les modèles sont les suivants :

• Bot vide
  • Il inclut un gestionnaire d'activités qui accueille un utilisateur dans la conversation en envoyant un message « hello world » au premier tour de la conversation.
• Bot écho
  • Il utilise un gestionnaire d'activités pour accueillir les utilisateurs et renvoyer l'entrée utilisateur.
• Bot cœur
  • Rassemble de nombreuses fonctionnalités du kit de développement logiciel (SDK) et illustre les meilleures pratiques pour un bot.
  • Utilise un gestionnaire d'activités pour accueillir les utilisateurs.
  • Utilise une boîte de dialogue de composant et des dialogues enfants pour gérer la conversation.
  • Les dialogues utilisent les caractéristiques de compréhension du langage (LUIS) et QnA Maker.

Remarque

Azure AI QnA Maker sera mis hors service le 31 mars 2025. À partir du 1er octobre 2022, vous ne pourrez plus créer de nouvelles ressources ou bases de connaissances QnA Maker. Une version plus récente de la fonctionnalité de questions et réponses est désormais disponible dans le cadre d’Azure AI Language.

La réponse aux questions personnalisées, une fonctionnalité d'Azure AI Language, est la version mise à jour du service QnA Maker. Pour plus d'informations sur la prise en charge des questions et réponses dans le kit de développement logiciel (SDK) Bot Framework, consultez Compréhension du langage naturel.

Remarque

Compréhension du langage (LUIS) sera mis hors service le 1er octobre 2025. À compter du 1er avril 2023, vous ne pourrez pas créer de nouvelles ressources LUIS. Une version plus récente de Compréhension du langage est désormais disponible dans le cadre d'Azure AI Language.

Compréhension du langage conversationnel (CLU), une fonctionnalité d'Azure AI Language, est la version mise à jour de LUIS. Pour plus d'informations sur la prise en charge de compréhension du langage dans le kit de développement logiciel (SDK) Bot Framework, consultez Compréhension du langage naturel.

Informations supplémentaires

Gestion des ressources de bot

Vous devez gérer les ressources de votre bot, telles que son ID d'application et son mot de passe, ainsi que des informations pour tous les services connectés. Lorsque vous déployez votre bot, il aura besoin d'un accès sécurisé à ces informations. Pour éviter toute complexité, la plupart des articles du kit de développement logiciel (SDK) Bot Framework ne décrivent pas comment gérer ces informations.

• Pour obtenir des informations générales sur la sécurité, consultez Recommandations de sécurité de Bot Framework.
• Pour gérer les clés et les secrets dans Azure, consultez Informations sur Azure Key Vault.

Adaptateurs de canal

Le kit de développement logiciel (SDK) vous permet également d'utiliser des adaptateurs de canaux, dans lesquels l'adaptateur lui-même effectue les tâches que le connecteur Bot Service effectuerait normalement pour un chaîne.

Le kit de développement logiciel (SDK) fournit quelques adaptateurs de chaîne dans certaines langues. D'autres adaptateurs de chaîne sont disponibles sur les référentiels Botkit et Community. Pour plus d'informations, consultez la table des canaux et adaptateurs du référentiel du kit de développement logiciel (SDK) Bot Framework.

L'API REST du connecteur de bot

Le kit de développement logiciel (SDK) Bot Framework s'inclut dans un enveloppement et s'appuie sur l'API REST du connecteur de Bot. Si vous souhaitez comprendre les requêtes HTTP sous-jacentes qui prennent en charge le Kit de développement logiciel (SDK), consultez les articles relatifs à l'authentification du Connecteur et ceux y sont associés. Les activités qu'un bot envoie et reçoit sont conformes au schéma d'activité Bot Framework.

Étapes suivantes

• Pour comprendre le rôle de l’état dans les bots, consultez Gestion de l’état.
• Pour comprendre les concepts clés du développement de bots pour Microsoft Teams, consultez Fonctionnement des bots Microsoft Teams.