Snabbstart: Lägga till en robot i chattappen

Artikel
11/05/2024

Lär dig hur du skapar konversations-AI-upplevelser i ett chattprogram med hjälp av den Azure Communication Services Chat-meddelandekanal som är tillgänglig i Azure Bot Service. I den här snabbstarten skapar du en robot med hjälp av BotFramework SDK. Sedan integrerar du roboten i ett chattprogram som du skapar med hjälp av Communication Services Chat SDK.

I den här snabbstarten lär du dig att:

Skapa och distribuera en robot i Azure
Hämta en Communication Services-resurs
Aktivera Chat-kanalen för Communication Services för roboten
Skapa en chattapp och lägg till roboten som deltagare
Utforska fler funktioner för din robot

Förutsättningar

Ett Azure-konto och en aktiv prenumeration. Skapa ett konto kostnadsfritt.
Visual Studio 2019 eller senare.
Den senaste versionen av .NET Core. (https://dotnet.microsoft.com/download/dotnet/).
Bot Framework SDK

Skapa och distribuera en robot i Azure

Om du vill använda Azure Communication Services-chatt som en kanal i Azure Bot Service distribuerar du först en robot. Om du vill distribuera en robot slutför du följande steg:

Skapa en Azure Bot Service-resurs
Hämta robotens app-ID och lösenord
Skapa en webbapp för att lagra robotappen
Skapa en meddelandeslutpunkt för roboten

Skapa en Azure Bot Service-resurs

Använd först Azure Portal för att skapa en Azure Bot Service-resurs. Chatkanalen Communication Services stöder chattrobotar med en enda klientorganisation, hanterade identitetsrobotar och robotar med flera klienter.

I den här snabbstarten använder vi en multitenant robot.
Om du vill konfigurera en eller managed identity en single-tenant robot läser du informationen om robotidentitet.
För en managed identity robot kan du behöva uppdatera robottjänstidentiteten.

Hämta robotens app-ID och applösenord

Hämta sedan microsofts app-ID och lösenord som har tilldelats din robot när den distribueras. Du använder dessa värden för senare konfigurationer.

Skapa en robotapp och publicera den till en webbapp

Om du vill skapa en robot kan du göra något av följande:

Ändra Bot Builder-exempel för ditt scenario, skapa en webbapp och distribuera sedan robotexemplet till det.
Använd Bot Builder SDK för att skapa och publicera en robot till en webbapp.

I den här snabbstarten använder vi Exemplet ekorobot från Bot Builder-exemplen.

Skapa en webbapp för att lagra robotappen

Om du vill skapa webbappen använder du antingen Azure CLI för att skapa en Azure App Service-resurs eller skapa appen i Azure Portal.

Så här skapar du en robotwebbapp med hjälp av Azure Portal:

I portalen väljer du Skapa en resurs. I sökrutan anger du webbapp. Välj panelen Webbapp .
I Skapa webbapp väljer eller anger du information för appen, inklusive den region där du vill distribuera appen.
Välj Granska + Skapa för att verifiera distributionen och granska distributionsinformationen. Välj sedan Skapa.
När webbappresursen skapas kopierar du den värdnamns-URL som visas i resursinformationen. URL:en är en del av slutpunkten som du skapar för webbappen.

Skapa en meddelandeslutpunkt för roboten

Azure Bot Service förväntar sig vanligtvis att Bot Application Web App Controller exponerar en slutpunkt i formuläret /api/messages. Slutpunkten hanterar alla meddelanden som skickas till roboten.

I robotresursen skapar du sedan en slutpunkt för webbappmeddelanden:

I Azure Portal går du till din Azure Bot-resurs. I resursmenyn väljer du Konfiguration.
I Konfiguration för Meddelandeslutpunkt klistrar du in värdnamns-URL:en för webbappen som du kopierade i föregående avsnitt. Lägg till URL:en med /api/messages.
Välj Spara.

Distribuera webbappen

Det sista steget för att skapa en robot är att distribuera webbappen. I den här snabbstarten använder du exempel på Ekorobot . Echo Bot-funktionen är begränsad till att upprepa användarens indata. Så här distribuerar du den till din webbapp i Azure:

Använd Git för att klona den här GitHub-lagringsplatsen:

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

Öppna Echo Bot-projektet i Visual Studio.
Öppna filen Appsettings.json i Visual Studio-projektet. Klistra in Microsoft-app-ID:t och applösenordet som du kopierade tidigare:
```
   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>",
       "MicrosoftAppTenantId": ""
   }
```
Använd sedan Visual Studio eller VS Code för C#-robotar för att distribuera roboten.

Du kan också använda kommandotolken för att distribuera en Azure-robot.
Högerklicka på EchoBot-projektet i Solution Explorer i Visual Studio och välj Publicera:
Välj Ny för att skapa en ny publiceringsprofil. Som Mål väljer du Azure:

För det specifika målet väljer du Azure App Service:
I distributionskonfigurationen väljer du webbappen i de resultat som visas när du har loggat in på ditt Azure-konto. Slutför profilen genom att välja Slutför och sedan Publicera för att starta distributionen.

Hämta en Communication Services-resurs

Nu när roboten har skapats och distribuerats skapar du en Communication Services-resurs som ska användas för att konfigurera en Communication Services-kanal:

Slutför stegen för att skapa en Communication Services-resurs.
Skapa en Communication Services-användare och utfärda en användaråtkomsttoken. Se till att ange omfånget till chatt. Kopiera tokensträngen och användar-ID-strängen.

Aktivera kommunikationstjänstens chattkanal

När du har en Communication Services-resurs kan du konfigurera en Communication Services-kanal i robotresursen. I den här processen genereras ett användar-ID för roboten.

I Azure Portal går du till din Azure Bot-resurs. I resursmenyn väljer du Kanaler. I listan över tillgängliga kanaler väljer du Azure Communications Services – Chat.
Välj Anslut för att se en lista över Kommunikationstjänster-resurser som är tillgängliga i din prenumeration.
I fönstret Ny anslutning väljer du kommunikationstjänstens chattresurs och väljer sedan Använd.
När resursinformationen verifieras visas ett robot-ID i kolumnen Bot Azure Communication Services ID . Du kan använda robot-ID:t för att representera roboten i en chatttråd med hjälp av Communication Services Chat AddParticipant API. När du har lagt till roboten i en chatt som deltagare börjar roboten ta emot chattrelaterade aktiviteter och den kan svara i chatttråden.

Skapa en chattapp och lägg till roboten som deltagare

Nu när du har robotens Communication Services-ID kan du skapa en chatttråd med roboten som deltagare.

Följ snabbstarten Lägg till chatt i din app

Följ stegen i snabbstarten Lägg till chatt i din app för att skapa en chattapp.

Ersätt <Resource_Endpoint> med slutpunkten För Kommunikationstjänster från steget Hämta en kommunikationstjänstresurs .
Ersätt <Access_Token> med användaråtkomsttoken från steget Hämta en kommunikationstjänstresurs .
Ersätt <Access_ID> med robotarna ACS_ID från steget Aktivera kommunikationstjänsters chattkanal .

Kör C#-chattprogrammet lokalt

Om du vill köra chattprogrammet lokalt använder du dotnet run kommandot:

dotnet run

Du bör få ett meddelande från roboten i konsolen med texten "Hello World".

Exempel på utdata>

1730405535010:Hello World

Fler saker du kan göra med en robot

En robot kan ta emot mer än ett oformaterad textmeddelande från en användare i en kommunikationstjänstchattkanal. Några av de aktiviteter som en robot kan ta emot från en användare är:

Konversationsuppdatering
Meddelandeuppdatering
Ta bort meddelande
Typindikator
Händelseaktivitet
Olika bifogade filer, inklusive adaptiva kort
Robotkanaldata

I nästa avsnitt visas några exempel för att illustrera dessa funktioner.

Skicka ett välkomstmeddelande när en ny användare läggs till i tråden

Den aktuella Echo Bot-logiken accepterar indata från användaren och ekar tillbaka den. Om du vill lägga till mer logik, till exempel svara på en kommunikationstjänsthändelse som lagts till av deltagare, kopierar du följande kod och klistrar in den i källfilen 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);
                        }
                    }
                }
            }
        }
    }
}

Skicka ett adaptivt kort

Kommentar

Anpassningsbara kort stöds endast i Azure Communication Services-användningsfall där alla chattdeltagare är Azure Communication Services-användare och inte för Användningsfall för Teams-interoprability.

Du kan skicka ett adaptivt kort till chatttråden för att öka engagemanget och effektiviteten. Ett adaptivt kort hjälper dig också att kommunicera med användare på olika sätt. Du kan skicka ett adaptivt kort från en robot genom att lägga till kortet som en bifogad robotaktivitet.

Här är ett exempel på hur du skickar ett adaptivt kort:

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);

Hämta exempelnyttolaster för adaptiva kort i Exempel och mallar.

För en chattanvändare lägger kommunikationstjänstens chattkanal till ett fält i meddelandemetadata som anger att meddelandet har en bifogad fil. I metadata är egenskapen inställd på microsoft.azure.communication.chat.bot.contenttype azurebotservice.adaptivecard.

Här är ett exempel på ett chattmeddelande som har ett adaptivt kort kopplat:

{
    "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"
}

Skicka ett meddelande från användare till robot

Du kan skicka ett grundläggande textmeddelande från en användare till roboten på samma sätt som du skickar ett sms till en annan användare.

Men när du skickar ett meddelande som har en bifogad fil från en användare till en robot lägger du till den här flaggan i Communication Services Chat-metadata:

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

Om du vill skicka en händelseaktivitet från en användare till en robot lägger du till den här flaggan i chatmetadata för Communication Services:

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

I följande avsnitt visas exempelformat för chattmeddelanden från en användare till en robot.

Enkelt textmeddelande

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

Meddelande med en bifogad fil

{
    "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"
}

Meddelande med en händelseaktivitet

En händelsenyttolast innehåller alla JSON-fält i meddelandeinnehållet utom Name. Fältet Name innehåller namnet på händelsen.

I följande exempel skickas händelsenamnet endOfConversation med nyttolasten "{field1":"value1", "field2": { "nestedField":"nestedValue" }} till roboten:

{
    "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"
}

Metadatafältet microsoft.azure.communication.chat.bot.contenttype krävs endast i ett meddelande som skickas från en användare till en robot.

Robotaktivitetsfält som stöds

I följande avsnitt beskrivs fält för robotaktivitet som stöds för robot-till-användare-flöden och användar-till-robot-flöden.

Bot-to-user-flöde

Följande robotaktivitetsfält stöds för robot-till-användare-flöden.

Aktiviteter

Meddelande
Typing

Fält för meddelandeaktivitet

Text
Attachments
AttachmentLayout
SuggestedActions
From.Name (Konverterad till Communication Services SenderDisplayName.)
ChannelData (Konverterad till Communication Services Chat Metadata. Om några ChannelData mappningsvärden är objekt serialiseras de i JSON-format och skickas som en sträng.)

Användar-till-robot-flöde

Dessa robotaktivitetsfält stöds för användar-till-robot-flöden.

Aktiviteter och fält

Meddelande
- Id (Meddelande-ID för Communication Services-chatt)
- TimeStamp
- Text
- Attachments
Konversationsuppdatering
- MembersAdded
- MembersRemoved
- TopicName
Meddelandeuppdatering
- Id (Uppdaterat meddelande-ID för Communication Services-chatt)
- Text
- Attachments
Ta bort meddelande
- Id (Meddelande-ID för borttagna kommunikationstjänster)
Event
- Name
- Value
Typing

Andra vanliga fält

Recipient.Id och Recipient.Name (Kommunikationstjänster Chattanvändar-ID och visningsnamn)
From.Id och From.Name (Kommunikationstjänster Chattanvändar-ID och visningsnamn)
Conversation.Id (Kommunikationstjänster, chatttråds-ID)
ChannelId (Communication Services Chat om det är tomt)
ChannelData (Meddelandemetadata för Communication Services-chatt)

Mönster för överlämning av robot

Ibland kan en robot inte förstå en fråga, eller så kan den inte svara på en fråga. En kund kan be i chatten att vara ansluten till en mänsklig agent. I dessa scenarier måste chatttråden överlämnas från roboten till en mänsklig agent. Du kan utforma ditt program för att överföra en konversation från en robot till en människa.

Hantera robot-till-robot-kommunikation

I vissa användningsfall måste två robotar läggas till i samma chatttråd för att tillhandahålla olika tjänster. I det här scenariot kan du behöva se till att en robot inte skickar automatiska svar till en annan robots meddelanden. Om den inte hanteras korrekt kan robotarnas automatiserade interaktion mellan dem resultera i en oändlig loop med meddelanden.

Du kan verifiera kommunikationstjänsternas användaridentitet för en meddelandesändare i aktivitetens From.Id egenskap. Kontrollera om den tillhör en annan robot. Vidta sedan den nödvändiga åtgärden för att förhindra ett kommunikationsflöde från robot till robot. Om den här typen av scenario resulterar i höga samtalsvolymer begränsar Kommunikationstjänsternas chattkanal begäranden och en robot kan inte skicka och ta emot meddelanden.

Läs mer om begränsningsgränser.

Felsöka

I följande avsnitt beskrivs olika sätt att felsöka vanliga scenarier.

Det går inte att lägga till chattkanal

I Microsoft Bot Framework-utvecklarportalen går du till Configuration>Bot Messaging för att kontrollera att slutpunkten har angetts korrekt.

Roboten får ett förbjudet undantag när den svarar på ett meddelande

Kontrollera att robotens Microsoft-app-ID och lösenord har sparats korrekt i robotkonfigurationsfilen som du laddar upp till webbappen.

Det går inte att lägga till roboten som deltagare

Kontrollera att robotens Communication Services-ID används korrekt när en begäran skickas för att lägga till en robot i en chatttråd.

Dela via