Principes de base du Microsoft Bot Framework

S’APPLIQUE À : KIT de développement logiciel (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 Bot Service est une plateforme cloud. Il héberge des bots et les met à la disposition de canaux, tels que Microsoft Teams, Facebook ou Slack.

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

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

Bot Framework Service envoie une mise à jour de conversation lorsqu’une partie se joint à la conversation. Par exemple, lors du démarrage d’une conversation avec le Bot Framework Emulator, vous pouvez voir deux activités de mise à jour de conversation (une pour l’utilisateur qui rejoint la conversation et une pour la jonction au bot). Pour distinguer ces activités de mise à jour de conversation, case activée qui est inclus dans la propriété ajoutée aux membres de l’activité.

L’activité de message contient des 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

Il appartient à chaque canal d’implémenter le protocole Bot Framework, et la façon dont chaque canal le fait peut être un peu différente. Par exemple, certains canaux envoient d’abord des activités de mise à jour de conversation, et d’autres envoient des activités de mise à jour de conversation après avoir envoyé la première activité de message. Un canal peut inclure 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. Toutefois, un bot peut répondre d’autres manières à une activité de message reçu, 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 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 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 conversationnelle. Bien que vous n’ayez pas besoin de comprendre le service REST pour utiliser le SDK, la compréhension de certaines de ses fonctionnalités peut être utile.

Les bots sont des applications qui ont une interface conversationnelle. 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.

Notes

La prise en charge des fonctionnalités fournies par le SDK et l’API REST varie selon le canal. Vous pouvez tester votre bot à l’aide de la Bot Framework Emulator, mais vous devez également tester toutes les fonctionnalités de votre bot sur chaque canal dans lequel vous envisagez de rendre votre bot disponible.

Les interactions impliquent l’échange d’activités, qui sont gérées à tour de rôle.

Activités

Chaque interaction entre l’utilisateur (ou un canal) et le bot est représentée sous forme d’activité. Le schéma d’activité bot Framework définit les activités qui peuvent être échangées entre un utilisateur ou un canal et un bot. Les activités peuvent représenter du texte ou de la parole humaine, 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. Vous pouvez considérer un tour comme le traitement associé au bot recevant une activité donnée.

Par exemple, un utilisateur peut demander à un bot d’effectuer une tâche spécifique. Le bot peut répondre avec une question pour obtenir plus d’informations sur la tâche, auquel moment ce tour se termine. Au tour suivant, le bot reçoit un nouveau message de l’utilisateur qui peut contenir la réponse à la question du bot, ou il peut représenter un changement d’objet ou une demande d’ignorer la demande initiale d’exécution de la tâche.

Structure de l’application bot

Le Kit de développement logiciel (SDK) définit une classe de bot qui gère le raisonnement conversationnel de l’application bot. Classe de bot :

• Reconnaît et interprète l’entrée de l’utilisateur.
• Raisons relatives à l’entrée et effectue les tâches pertinentes.
• Génère des réponses sur ce que le bot fait ou a fait.

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

• Fournit une méthode de gestion des requêtes à partir de et des méthodes pour générer des requêtes vers le canal de l’utilisateur.
• Inclut un pipeline d’intergiciels, qui inclut le traitement des tours en dehors du gestionnaire de tour de votre bot.
• Appelle le gestionnaire de tour du bot et intercepte les erreurs qui ne sont pas autrement gérées dans le gestionnaire de tour.

En outre, les bots doivent souvent récupérer et stocker l’état à chaque tour. L’état est géré via des classes d’accesseurs de stockage, d’état de bot et de propriété . Le KIT de développement logiciel (SDK) ne fournit pas de stockage intégré, mais fournit des abstractions pour le stockage et quelques implémentations d’une couche de stockage. La rubrique gestion de l’état décrit ces fonctionnalités d’état et de stockage.

Le Kit de développement logiciel (SDK) ne vous oblige pas à utiliser une couche d’application spécifique pour envoyer et recevoir des requêtes web. Bot Framework a des modèles et des exemples pour ASP.NET (C#), restify (JavaScript) et aiohttp (Python). Toutefois, vous pouvez choisir d’utiliser une autre couche d’application 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.

Notes

Les sdk JavaScript et C# de Bot Framework continueront d’être pris en charge, mais les SDK Python et Java sont 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 au sein de ce dépôt seront entrepris.

Les bots existants créés avec ces SDK continueront de fonctionner.

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

Pour plus d’informations, consultez L’avenir de la génération de bots.

Logique du bot

L’objet bot contient le raisonnement ou la logique conversationnelle d’un tour et expose un gestionnaire de tour, qui est la méthode qui peut accepter les activités entrantes 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 et sous-types d’activité entrants sont les événements. Envisagez un gestionnaire d’activités pour les bots qui ont des interactions limitées et courtes avec l’utilisateur.
  • Utilisez un gestionnaire d’activités et implémentez des gestionnaires pour chaque type d’activité ou sous-type que votre bot reconnaîtra et réagira.
  • Utilisez un gestionnaire d’activités Teams pour créer des bots qui peuvent se connecter au canal Teams. (Le canal Teams nécessite que le bot gère un comportement spécifique au canal.)
• La bibliothèque de dialogues fournit un modèle basé 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 boîtes de dialogue sur les composants et les cascades.
• Implémentez votre propre classe de bot et fournissez votre propre logique pour gérer chaque tour. Pour obtenir un exemple, découvrez comment créer vos propres invites pour collecter les entrées 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 requête (la charge utile de la requête, traduite en une activité) et l’en-tête de la requête 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 via son pipeline middleware .
• Il envoie ensuite l’objet de contexte au gestionnaire de tour de l’objet bot.

L’adaptateur également :

• Met en forme et envoie les activités de réponse. Ces réponses sont généralement des messages destinés à l’utilisateur, mais peuvent également inclure des informations à consommer directement par le canal de l’utilisateur.
• Met en évidence d’autres méthodes fournies par l’API REST bot Connector, telles que la mise à jour du message et la suppression du message.
• Intercepte les erreurs ou les exceptions qui ne sont pas interceptées pour le tour.

Contexte de 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. Non seulement il transporte l’activité entrante vers tous les composants middleware et la logique d’application, mais il fournit également le mécanisme par lequel les composants middleware et la logique du bot peuvent envoyer des activités sortantes.

Middlewares

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. Le middleware implémente une méthode on turn que l’adaptateur appelle.

Le gestionnaire de tours prend un contexte de tour comme argument. En général, la logique d’application s’exécutant à l’intérieur de la fonction de gestionnaire de tour traite le contenu de l’activité entrante et génère une ou plusieurs activités en réponse, en envoyant ces activités sortantes à l’aide de la fonction d’activité d’envoi sur le contexte de tour. 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 d’intergiciel s’exécutent avant et après la fonction de gestionnaire de tour du bot. L’exécution est intrinsèquement imbriquée et, en tant que telle, parfois appelée être comme un oignon.

La rubrique middleware décrit plus en détail les intergiciels.

État du bot et stockage

Comme avec d’autres applications web, un bot est intrinsèquement sans état. L’é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 fournit des abstractions de gestion de la couche de stockage et de l’état pour faciliter la gestion de l’état.

La rubrique gestion de l’état décrit ces fonctionnalités d’état et 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. Il devra également provisionner des ressources pour votre bot en fonction de 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 d’é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 effectués. 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 modèle 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.

Notes

Le bot dispose de 15 secondes pour accepter l’appel avec un status 200 sur la plupart des canaux. Si le bot ne répond pas dans les 15 secondes, une erreur HTTP GatewayTimeout (504) se produit.

Pile de traitement d’une activité

Nous allons explorer le diagramme de séquence précédent en nous concentrant sur l’arrivée d’une activité de message.

Le canal envoie le message de l’utilisateur au Bot Service Azure, 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 sont utilisés pour les bots C#, et une infrastructure populaire telle 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 JSON est désérialisé pour créer l’objet d’activité qui est ensuite remis à l’adaptateur via sa méthode d’activité de processus . 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éponse d’activité d’envoi, de mise à jour et de suppression . Chaque méthode de réponse s’exécute dans un processus asynchrone.

Important

Le thread qui gère le tour du bot principal traite de l’élimination de l’objet de contexte lorsque cela est effectué. 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 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 sont fournis pour chaque version linguistique du SDK. Tous les modèles fournissent une implémentation et un adaptateur de point de terminaison par défaut. Chaque modèle comprend :

• Provisionnement des ressources
• Implémentation de point de terminaison HTTP spécifique au langage qui achemine les activités entrantes vers une carte.
• Objet adaptateur
• Objet bot

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

• Bot vide
  • 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 d’écho
  • Utilise un gestionnaire d’activités pour accueillir les utilisateurs et renvoyer les entrées utilisateur.
• Bot principal
  • Regroupe de nombreuses fonctionnalités du KIT de développement logiciel (SDK) et présente 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 boîtes de dialogue utilisent les fonctionnalités Language Understanding (LUIS) et QnA Maker.

Notes

Azure QnA Maker sera mis hors service le 31 mars 2025. À compter du 1er octobre 2022, vous ne pourrez pas créer de 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 Cognitive Service for Language.

Les réponses aux questions personnalisées, une fonctionnalité d’Azure Cognitive Service for Language, sont la version mise à jour du service QnA Maker. Pour plus d’informations sur la prise en charge des questions-réponses dans le Kit de développement logiciel (SDK) Bot Framework, consultez Compréhension du langage naturel.

Notes

Language Understanding (LUIS) sera mis hors service le 1er octobre 2025. À compter du 1er avril 2023, vous ne pourrez pas créer de ressources LUIS. Une version plus récente de la compréhension du langage est désormais disponible dans le cadre d’Azure Cognitive Service for Language.

La compréhension du langage conversationnel (CLU), une fonctionnalité d’Azure Cognitive Service for Language, est la version mise à jour de LUIS. Pour plus d’informations sur la prise en charge de la 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 les informations relatives aux services connectés. Lorsque vous déployez votre bot, il a 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 Instructions de sécurité de Bot Framework.
• Pour gérer les clés et les secrets dans Azure, consultez À propos d’Azure Key Vault.

Cartes de canal

Le Kit de développement logiciel (SDK) vous permet également d’utiliser des adaptateurs de canal, dans lesquels l’adaptateur lui-même effectue également les tâches que le service Bot Connector effectue normalement pour un canal.

Le Kit de développement logiciel (SDK) fournit quelques adaptateurs de canal dans certaines langues. D’autres adaptateurs de canal sont disponibles via les référentiels Botkit et Community. Pour plus d’informations, consultez le tableau des canaux et des adaptateurs du référentiel du Kit de développement logiciel (SDK) Bot Framework.

L’API REST Bot Connector

Le Kit de développement logiciel (SDK) Bot Framework encapsule et s’appuie sur l’API REST Bot Connector. Si vous souhaitez comprendre les requêtes HTTP sous-jacentes qui prennent en charge le SDK, consultez les articles Sur l’authentification du connecteur et les articles 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.