Démarrage rapide : Ajout d’un bot à une application de conversation

Article
11/07/2024

Découvrez comment créer des expériences d’intelligence artificielle conversationnelle dans notre application de conversation en utilisant le canal de messagerie Azure Communication Services – Conversation disponible dans Azure Bot Service. Dans ce guide de démarrage rapide, vous créez un bot à l’aide du Kit de développement logiciel (SDK) BotFramework. Ensuite, vous intégrez le bot à une application de conversation que vous créez à l’aide du Kit de développement logiciel (SDK) Communication Services Chat.

Dans ce guide de démarrage rapide, vous apprenez à :

Créer et déployer un bot dans Azure
Obtenir une ressource Communication Services
Activer le canal Conversation de Communication Services pour le bot
Créer une application de conversation et ajouter le bot aux participants
Explorer davantage de fonctionnalités pour votre bot

Prérequis

Un compte et un abonnement Azure actifs. Créez un compte gratuitement.
Visual Studio 2019 ou ultérieur.
La dernière version de .NET Core. (https://dotnet.microsoft.com/download/dotnet/).
Kit de développement logiciel (SDK) Bot Framework

Créer et déployer un bot dans Azure

Pour utiliser la conversation Azure Communication Services comme canal dans Azure Bot Service, déployez d’abord un bot. Pour déployer un bot, procédez comme suit :

Créer une ressource Azure Bot Service
Obtenir l’ID d’application et le mot de passe du bot
Créer une application web pour contenir la logique du bot
Créer un point de terminaison de messagerie pour le bot

Créer une ressource d’Azure Bot Service

Tout d’abord, utilisez le Portail Azure pour créer une ressource Azure Bot Service. Le canal Communication Services Chat prend en charge les bots monolocataires , les bots d’identité managée et les bots multilocataires.

Pour les besoins de ce démarrage rapide, nous allons utiliser un bot multitenant.
Pour configurer un bot single-tenant ou managed identity, étudiez Informations d’identité des bots.
Pour un botmanaged identity, vous devrez peut-être mettre à jour l’identité du service bot.

Obtenir l’ID d’application et le mot de passe d’application du bot

Ensuite, obtenez l’ID d’application et le mot de passe Microsoft qui sont attribués à votre bot lors de son déploiement. Vous utilisez ces valeurs pour les configurations ultérieures.

Créer une application bot et la publier sur une application web

Pour créer un bot, vous pouvez effectuer l’une des opérations suivantes :

Réviser les exemples Bot Builder pour votre scénario, créer une application web, puis déployer votre exemple de bot sur celui-ci.
Utiliser le Kit de développement logiciel (SDK) Bot Builder pour créer et publier un bot sur une application web.

Pour ce démarrage rapide, nous allons utiliser l’exemple Echo Bot des exemples Bot Builder.

Créer une application web pour contenir la logique du bot

Pour créer l’application web, utilisez Azure CLI pour créer une ressource Azure App Service ou créez l’application dans le Portail Azure.

Pour créer une application web de bot à l’aide du Portail Azure :

Dans le portail, sélectionnez Créer une ressource. Dans la zone de recherche, entrez application web. Sélectionnez la vignette Application web.
Dans Créer une application web, sélectionnez ou entrez les détails de l’application, y compris la région dans laquelle vous souhaitez déployer l’application.
Sélectionnez Réviser + Créer pour valider le déploiement et passer en revue les détails du déploiement. Sélectionnez ensuite Create (Créer).
Lorsque la ressource d’application web est créée, copiez l’URL du nom d’hôte qui s’affiche dans les détails de la ressource. L’URL fait partie du point de terminaison que vous créez pour l’application web.

Créer un point de terminaison de messagerie pour le bot

Azure Bot Service s’attend généralement à ce que le contrôleur d’application web du bot pour exposer un point de terminaison dans le formulaire /api/messages. Le point de terminaison gère tous les messages envoyés au bot.

Ensuite, dans la ressource de bot, créez un point de terminaison de messagerie d’application web :

Dans le portail Azure, accédez à votre ressource Azure Bot. Dans le menu Ressource, sélectionnez Configuration.
Dans Configuration, pour Point de terminaison de messagerie, collez l’URL du nom d’hôte de l’application web que vous avez copiée dans la section précédente. Ajoutez à l’URL avec /api/messages.
Sélectionnez Enregistrer.

Déployer l’application web

La dernière étape pour créer un bot consiste à déployer l’application web. Pour ce démarrage rapide, utilisez l’exemple Echo Bot. La fonctionnalité Echo Bot se limite à l’écho de l’entrée utilisateur. Voici comment le déployer sur votre application web dans Azure :

Utilisez Git pour cloner ce référentiel GitHub :

git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

Dans Visual Studio, ouvrez le projet Echo Bot.
Dans le projet Visual Studio, ouvrez le fichier Appsettings.json. Collez l’ID d’application Microsoft et le mot de passe d’application que vous avez copiés précédemment :
```
   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>",
       "MicrosoftAppTenantId": ""
   }
```
Ensuite, utilisez les bots Visual Studio ou VS Code pour C# pour déployer le bot.

Vous pouvez également utiliser une fenêtre d’invite de commandes pour déployer un bot Azure.
Dans Visual Studio, dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet EchoBot, puis sélectionnez Publier :
Sélectionnez Nouveau pour créer un profil de publication. Pour Cible, sélectionnez Azure :

Pour la cible spécifique, sélectionnez Azure App Service :
Dans la configuration du déploiement, sélectionnez l’application web dans les résultats qui s’affichent une fois que vous vous êtes connecté à votre compte Azure. Pour terminer le profil, sélectionnez Terminer, puis sélectionnez Publier pour lancer le déploiement.

Obtenir une ressource Communication Services

Maintenant que votre bot est créé et déployé, créez une ressource Communication Services à utiliser pour configurer un canal Communication Services :

Effectuez les étapes pourcréer une ressource Communication Services.
Créez un utilisateur Communication Services et émettez un jeton d’accès utilisateur. Veillez à définir l’étendue sur conversation. Copiez la chaîne de jeton et la chaîne d’ID utilisateur.

Activer le canal Conversation de Communication Services

Lorsque vous disposez d’une ressource Communication Services, vous pouvez configurer un canal Communication Services dans la ressource de bot. Dans ce processus, un ID utilisateur est généré pour le bot.

Dans le portail Azure, accédez à votre ressource Azure Bot. Dans le menu de ressources, sélectionnez Canaux. Dans la liste des canaux disponibles, sélectionnez Azure Communications Services - Conversation.
Sélectionnez Se connecter pour afficher la liste des ressources Communication Services disponibles dans votre abonnement.
Dans le volet Nouvelle connexion, sélectionnez la ressource de conversation Communication Services, puis sélectionnez Appliquer.
Lorsque les détails de la ressource sont vérifiés, un ID de bot s’affiche dans la colonne ID Azure Communication Services du bot. Vous pouvez utiliser l’ID de bot pour représenter le bot dans un fil de conversation à l’aide de l’API AddParticipant de conversation Communication Services. Une fois que vous avez ajouté le bot à une conversation en tant que participant, le bot commence à recevoir des activités liées à la conversation, et il peut répondre dans le fil de conversation.

Créer une application de conversation et ajouter le bot aux participants

Maintenant que vous disposez de l’ID Communication Services du bot, vous pouvez créer un fil de conversation qui compte le bot parmi les participants.

Suivre le démarrage rapide « Ajouter une conversation à votre application »

Suivez les étapes décrites dans le démarrage rapide Ajouter une conversation à votre application pour créer une application de conversation.

Remplacez <Resource_Endpoint> par le point de terminaison Communication Services de l’étape Obtenir une ressource Communication Service.
Remplacez <Access_Token> par le jeton d’accès utilisateur de l’étape Obtenir une ressource Communication Service.
Remplacez <Access_ID> par les bots ACS_ID de l’étape Activer le canal Communication Services Chat.

Exécuter l’application de conversation C# localement

Pour exécuter l’application de conversation localement, utilisez la commande dotnet run :

dotnet run

Vous devez recevoir un message du bot dans la console qui dit « Hello World ».

Exemple de sortie :

1730405535010:Hello World

Autres possibilités offertes par les bots

Un bot peut recevoir plus qu’un message en texte brut d’un utilisateur dans un canal de conversation Communications Services. Voici quelques-unes des activités qu’un bot peut recevoir d’un utilisateur :

Mise à jour de conversation
Mise à jour de message
Suppression de message
Indicateur de saisie
Activité d’événement
Diverses pièces jointes, y compris les cartes adaptatives
Données de canal de bot

Les sections suivantes présentent des exemples pour illustrer ces fonctionnalités.

Envoi d’un message d’accueil lorsqu’un nouvel utilisateur est ajouté au thread

La logique actuelle d’Echo Bot accepte l’entrée de l’utilisateur et la renvoie. Si vous souhaitez ajouter une logique supplémentaire (par exemple la réponse à un événement Communication Services ajouté par un participant), copiez le code suivant et collez-le dans le fichier source EchoBot.cs :

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

Envoi d’une carte adaptative

Remarque

Les cartes adaptatives sont uniquement prises en charge dans les cas d’utilisation d’Azure Communication Services où tous les participants au chat sont des utilisateurs Azure Communication Services, et non pour les cas d’utilisation d’interopérabilité Teams.

Vous pouvez envoyer une carte adaptative au fil de conversation pour augmenter l’engagement et l’efficacité. Une carte adaptative vous permet également de communiquer avec les utilisateurs de différentes façons. Vous pouvez envoyer une carte adaptative à partir d’un bot en ajoutant la carte en tant que pièce jointe d’activité de bot.

Voici un exemple d’envoi d’une carte adaptative :

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);

Trouvez des exemples de charges utiles pour les cartes adaptatives dans Exemples et modèles.

Pour un utilisateur de conversation, le canal de conversation Communication Services ajoute un champ aux métadonnées du message qui indique que le message a une pièce jointe. Dans les métadonnées, la propriété de microsoft.azure.communication.chat.bot.contenttype est définie sur azurebotservice.adaptivecard.

Voici un exemple de message de conversation auquel une carte adaptative est jointe :

{
    "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
    "senderDisplayName": "BotDisplayName",
    "metadata": {
    "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
    },
 "messageType": "Text"
}

Envoyer un message d’utilisateur à bot

Vous pouvez envoyer un message texte basique de l’utilisateur au bot de la même façon que vous envoyez un message texte à un autre utilisateur.

Toutefois, pendant l’envoi d’un message contenant une pièce jointe entre un utilisateur et un bot, ajoutez cet indicateur aux métadonnées de conversation Communication Services :

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

Pour envoyer une activité d’événement d’un utilisateur à un bot, ajoutez cet indicateur aux métadonnées de conversation Communication Services :

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

Les sections suivantes présentent des exemples de formats pour les messages de conversation d’un utilisateur vers un bot.

Envoyer un message texte simple

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

Message avec une pièce jointe

{
    "content": "{
                        \"text\":\"sample text\", 
                        \"attachments\": [{
                            \"contentType\":\"application/vnd.microsoft.card.adaptive\",
                            \"content\": { \"*adaptive card payload*\" }
                        }]
        }",
    "senderDisplayName": "Acs-Dev-Bot",
    "metadata": {
        "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
        "text": "random text",
        "key1": "value1",
        "key2": "{\r\n  \"subkey1\": \"subValue1\"\r\n}"
    },
        "messageType": "Text"
}

Message avec une activité d’événement

Une charge utile d’événement inclut tous les champs JSON dans le contenu du message, à l’exception de Name. Le champ Name contient le nom de l’événement.

Dans l’exemple suivant, le nom de l’événement endOfConversation avec la charge utile "{field1":"value1", "field2": { "nestedField":"nestedValue" }} est envoyé au bot :

{
    "content":"{
                   \"name\":\"endOfConversation\",
                   \"field1\":\"value1\",
                   \"field2\": {  
                       \"nestedField\":\"nestedValue\"
                    }
               }",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{  
                   "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
                   "text":"random text",
                   "key1":"value1",
                   "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n}"
               },
    "messageType": "Text"
}

Le champ de métadonnées microsoft.azure.communication.chat.bot.contenttype est requis uniquement dans un message envoyé d’un utilisateur à un bot.

Champs d’activité de bot pris en charge

Les sections suivantes décrivent les champs d’activité de bot pris en charge pour les flux de bot à utilisateur et d’utilisateur à bot.

Flux de bot à utilisateur

Les champs d’activité de bot suivants sont pris en charge pour les flux de bot à utilisateur.

Activités

Message
Saisie

Champs d’activité de message

Text
Attachments
AttachmentLayout
SuggestedActions
From.Name (Converti en Communication Services SenderDisplayName.)
ChannelData (Converti en Communication Services Chat Metadata. Si des valeurs de mappage ChannelData sont des objets, elles sont sérialisées au format JSON et envoyées sous forme de chaîne.)

Flux d’utilisateur à bot

Ces champs d’activité de bot sont pris en charge pour les flux d’utilisateur à bot.

Activités et champs

Message
- Id (ID de message de conversation Communication Services)
- TimeStamp
- Text
- Attachments
Mise à jour de conversation
- MembersAdded
- MembersRemoved
- TopicName
Mise à jour de message
- Id (ID de message de conversation Communication Services mis à jour)
- Text
- Attachments
Suppression de message
- Id (ID de message de conversation Communication Services supprimé)
Événement
- Name
- Value
Saisie

Autres champs communs

Recipient.Id et Recipient.Name (ID d’utilisateur et nom d’affichage de conversation Communication Services)
From.Id et From.Name (ID d’utilisateur et nom d’affichage de conversation Communication Services)
Conversation.Id (ID de fil de conversation Communication Services)
ChannelId (conversation avec Communication Services si vide)
ChannelData (métadonnées de message de conversation Communication Services)

Modèles de transfert de bot

Parfois, un bot ne comprend pas une question ou ne peut pas répondre à une question. Un client peut demander dans la conversation à être mis en relation avec un agent humain. Dans ces scénarios, le fil de conversation doit être transféré du bot à un agent humain. Vous pouvez concevoir votre application pour faire passer la conversation d’un bot à un humain.

Gérer la communication de bot à bot

Dans certains cas d’usage, deux bots doivent être ajoutés au même fil de conversation pour fournir des services différents. Dans ce scénario, vous devrez peut-être vous assurer qu’un bot n’envoie pas de réponses automatisées aux messages d’un autre bot. Si elle n’est pas gérée correctement, l’interaction automatisée des bots entre eux peut entraîner une boucle infinie de messages.

Vous pouvez vérifier l’identité de l’utilisateur Communication Services d’un expéditeur de message dans la propriété From.Id de l’activité. Vérifiez s’il appartient à un autre bot. Ensuite, effectuez l’action requise pour empêcher un flux de communication bot à bot. Si ce type de scénario entraîne des volumes d’appels élevés, le canal de conversation Communication Services limite les demandes et un bot ne peut pas envoyer et recevoir des messages.

En savoir plus sur les limites de l’accélérateur.

Dépanner

Les sections suivantes décrivent les différentes façons de résoudre les scénarios courants.

Impossible d’ajouter le canal de conversation

Dans le portail des développeurs Microsoft Bot Framework, accédez à Configuration>messagerie Bot pour vérifier que le point de terminaison a été correctement défini.

Le bot obtient une exception d’interdiction lors de la réponse à un message

Vérifiez que l’ID et le mot de passe de l’application Microsoft du bot sont correctement enregistrés dans le fichier de configuration du bot que vous chargez dans l’application web.

Le bot ne peut pas être ajouté comme participant

Vérifiez que l’ID Communication Services du bot est utilisé correctement pendant l’envoi d’une demande d’ajout de bot à un fil de conversation.

Étapes suivantes

Bien démarrer avec les conversations

Vous souhaiterez peut-être également :

Familiarisez-vous avec les concepts relatifs aux conversations.
Comprendre comment les tarifs sont appliqués pour les conversations

Partager via