Rychlý start: Přidání robota do chatovací aplikace

Článek
11/05/2024

Naučte se vytvářet konverzační prostředí umělé inteligence v chatovací aplikaci pomocí kanálu zasílání zpráv chatu v Azure Communication Services, který je k dispozici ve službě Azure Bot Service. V tomto rychlém startu vytvoříte robota pomocí sady BotFramework SDK. Pak robota integrujete do chatovací aplikace, kterou vytvoříte pomocí sady SDK chatu komunikačních služeb.

V tomto rychlém startu se naučíte:

Vytvoření a nasazení robota v Azure
Získání prostředku Komunikační služby
Povolení chatovacího kanálu komunikační služby pro robota
Vytvoření chatovací aplikace a přidání robota jako účastníka
Prozkoumání dalších funkcí robota

Požadavky

Účet Azure a aktivní předplatné. Vytvořte si bezplatný účet.
Visual Studio 2019 nebo novější
Nejnovější verze .NET Core. (https://dotnet.microsoft.com/download/dotnet/).
Sada SDK služby Bot Framework

Vytvoření a nasazení robota v Azure

Pokud chcete chat azure Communication Services použít jako kanál ve službě Azure Bot Service, nejprve nasaďte robota. Pokud chcete nasadit robota, proveďte tyto kroky:

Vytvoření prostředku Azure Bot Service
Získání ID a hesla aplikace robota
Vytvoření webové aplikace pro uložení aplikace robota
Vytvoření koncového bodu zasílání zpráv pro robota

Vytvoření prostředku Azure Bot Service

Nejprve pomocí webu Azure Portal vytvořte prostředek Azure Bot Service. Chatovací kanál komunikačních služeb podporuje roboty s jedním tenantem, roboty spravovaných identit a roboty s více tenanty.

Pro účely tohoto rychlého startu použijeme robota multitenant .
Pokud chcete nastavit nebo robotasingle-tenant, projděte si informace o identitě robota.managed identity
managed identity U robota možná budete muset aktualizovat identitu služby Bot Service.

Získání ID aplikace a hesla aplikace robota

Dále získejte ID a heslo aplikace Microsoftu, které jsou přiřazené vašemu robotovi při nasazení. Tyto hodnoty použijete pro pozdější konfigurace.

Vytvoření aplikace robota a jeho publikování do webové aplikace

Pokud chcete vytvořit robota, můžete udělat jednu z těchto věcí:

Revidujte ukázky Bot Builderu pro váš scénář, vytvořte webovou aplikaci a pak do ní nasaďte ukázku robota.
Pomocí sady SDK bot Builderu můžete vytvořit a publikovat robota do webové aplikace.

Pro účely tohoto rychlého startu použijeme ukázku Echo Bot z ukázek Bot Builderu.

Vytvoření webové aplikace pro uložení aplikace robota

Pokud chcete vytvořit webovou aplikaci, vytvořte pomocí Azure CLI prostředek služby Aplikace Azure nebo vytvořte aplikaci na webu Azure Portal.

Vytvoření webové aplikace robota pomocí webu Azure Portal:

Na portálu vyberte Vytvořit prostředek. Do vyhledávacího pole zadejte webovou aplikaci. Vyberte dlaždici webové aplikace .
V části Vytvořit webovou aplikaci vyberte nebo zadejte podrobnosti o aplikaci, včetně oblasti, do které chcete aplikaci nasadit.
Výběrem možnosti Zkontrolovat a vytvořit ověřte nasazení a zkontrolujte podrobnosti o nasazení. Potom vyberte Vytvořit.
Po vytvoření prostředku webové aplikace zkopírujte adresu URL názvu hostitele, která se zobrazí v podrobnostech o prostředku. Adresa URL je součástí koncového bodu, který vytvoříte pro webovou aplikaci.

Vytvoření koncového bodu zasílání zpráv pro robota

Služba Azure Bot Service obvykle očekává, že řadič webové aplikace robota zveřejní koncový bod ve formuláři /api/messages. Koncový bod zpracovává všechny zprávy odeslané robotovi.

Dále v prostředku robota vytvořte koncový bod zasílání zpráv webové aplikace:

Na webu Azure Portal přejděte k prostředku robota Azure. V nabídce prostředků vyberte Konfigurace.
V části Konfigurace vložte do koncového bodu zasílání zpráv adresu URL názvu hostitele webové aplikace, kterou jste zkopírovali v předchozí části. Připojte adresu URL pomocí /api/messages.
Zvolte Uložit.

Nasazení webové aplikace

Posledním krokem k vytvoření robota je nasazení webové aplikace. Pro účely tohoto rychlého startu použijte ukázku Echo Bota . Funkce Echo Bot je omezená na ozvěnu vstupu uživatele. Tady je postup, jak ho nasadit do webové aplikace v Azure:

Pomocí Gitu naklonujte toto úložiště GitHubu:

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

V sadě Visual Studio otevřete projekt Echo Bot.
V projektu sady Visual Studio otevřete soubor Appsettings.json . Vložte ID aplikace a heslo aplikace Microsoftu, které jste si zkopírovali dříve:
```
   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>",
       "MicrosoftAppTenantId": ""
   }
```
Dále pomocí sady Visual Studio nebo VS Code pro roboty jazyka C# nasaďte robota.

K nasazení robota Azure můžete použít také okno příkazového řádku.
V sadě Visual Studio v Průzkumník řešení klikněte pravým tlačítkem na projekt EchoBot a vyberte Publikovat:
Vyberte Nový a vytvořte nový profil publikování. Jako cíl vyberte Azure:

Pro konkrétní cíl vyberte Aplikace Azure Service:
V konfiguraci nasazení vyberte ve výsledcích webovou aplikaci, která se zobrazí po přihlášení ke svému účtu Azure. Pokud chcete profil dokončit, vyberte Dokončit a pak výběrem možnosti Publikovat spusťte nasazení.

Získání prostředku Komunikační služby

Teď, když je robot vytvořený a nasazený, vytvořte prostředek komunikační služby, který se použije k nastavení kanálu Komunikační služby:

Dokončete kroky pro vytvoření prostředku služby Communication Services.
Vytvoření uživatele komunikační služby a vystavení přístupového tokenu uživatele Nezapomeňte nastavit obor chatu. Zkopírujte řetězec tokenu a řetězec ID uživatele.

Povolení kanálu chatu komunikačních služeb

Pokud máte prostředek Komunikační služby, můžete v prostředku robota nastavit kanál komunikační služby. V tomto procesu se pro robota vygeneruje ID uživatele.

Na webu Azure Portal přejděte k prostředku robota Azure. V nabídce prostředků vyberte Kanály. V seznamu dostupných kanálů vyberte Azure Communications Services – Chat.
Výběrem možnosti Připojit zobrazíte seznam prostředků komunikačních služeb, které jsou k dispozici ve vašem předplatném.
V podokně Nové připojení vyberte prostředek chatu Komunikační služby a pak vyberte Použít.
Po ověření podrobností o prostředku se ID robota zobrazí ve sloupci ID služby Bot Azure Communication Services. ID robota můžete použít k reprezentaci robota ve vlákně chatu pomocí rozhraní API AddParticipant služby Communication Services. Jakmile robota přidáte do chatu jako účastníka, robot začne přijímat aktivity související s chatem a může reagovat ve vlákně chatu.

Vytvoření chatovací aplikace a přidání robota jako účastníka

Teď, když máte ID komunikační služby robota, můžete vytvořit chatovací vlákno s robotem jako účastníkem.

Rychlý start pro přidání chatu do aplikace

Pomocí kroků v rychlém startu Pro přidání chatu do aplikace vytvořte chatovací aplikaci.

Nahraďte <Resource_Endpoint> koncovým bodem komunikační služby v kroku Získání prostředku komunikační služby.
Nahraďte <Access_Token> přístupovým tokenem uživatele z kroku Získání prostředku komunikační služby.
Nahraďte <Access_ID> roboty ACS_ID z kroku Povolit chatovací kanál komunikačních služeb.

Místní spuštění chatovací aplikace jazyka C#

Pokud chcete chatovací aplikaci spustit místně, použijte příkaz dotnet run :

dotnet run

V konzole by se měla zobrazit zpráva s textem "Hello World".

Příklad výstupu:

1730405535010:Hello World

Další možnosti, které můžete dělat s robotem

Robot může obdržet více než zprávu ve formátu prostého textu od uživatele v kanálu chatu služby Communications Services. Mezi aktivity, které robot může od uživatele přijímat, patří:

Aktualizace konverzací
Aktualizace zprávy
Odstranění zprávy
Indikátor psaní
Aktivita události
Různé přílohy, včetně adaptivních karet
Data kanálu robota

Další části ukazují některé ukázky, které ilustrují tyto funkce.

Odeslání uvítací zprávy při přidání nového uživatele do vlákna

Aktuální logika Echo Bot přijímá vstup od uživatele a vrací ho zpět. Pokud chcete přidat další logiku, například reagovat na událost komunikačních služeb přidanou účastníkem, zkopírujte následující kód a vložte ho do zdrojového souboru 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);
                        }
                    }
                }
            }
        }
    }
}

Odeslání adaptivní karty

Poznámka:

Adaptivní karty jsou podporovány pouze v případech použití služeb Azure Communication Services, kdy všichni účastníci chatu jsou uživatelé služeb Azure Communication Services, a ne pro případy použití interoprability Teams.

Pokud chcete zvýšit zapojení a efektivitu, můžete do vlákna chatu odeslat adaptivní kartu. Adaptivní karta také pomáhá komunikovat s uživateli různými způsoby. Adaptivní kartu můžete odeslat z robota tak, že kartu přidáte jako přílohu aktivity robota.

Tady je příklad odeslání adaptivní karty:

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

Získejte ukázkové datové části pro adaptivní karty v ukázkách a šablonách.

Pro chatovacího uživatele přidá kanál chatu komunikační služby do metadat zprávy pole, které označuje, že zpráva obsahuje přílohu. V metadatech microsoft.azure.communication.chat.bot.contenttype je vlastnost nastavena na azurebotservice.adaptivecard.

Tady je příklad zprávy chatu s připojenou adaptivní kartou:

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

Odeslání zprávy od uživatele do robota

Základní textovou zprávu můžete odeslat uživateli do robota stejným způsobem, jakým posíláte textovou zprávu jinému uživateli.

Když ale odešlete zprávu s přílohou od uživatele do robota, přidejte tento příznak do metadat chatu služby Communication Services:

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

Pokud chcete odeslat aktivitu události od uživatele do robota, přidejte tento příznak do metadat chatu služby Communication Services:

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

Následující části ukazují ukázkové formáty chatovacích zpráv od uživatele k robotovi.

Jednoduchá textová zpráva

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

Zpráva s přílohou

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

Zpráva s aktivitou události

Datová část události obsahuje všechna pole JSON v obsahu zprávy s výjimkou Name. Pole Name obsahuje název události.

V následujícím příkladu se do robota odešle název endOfConversation události s datovou částí "{field1":"value1", "field2": { "nestedField":"nestedValue" }} :

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

Pole microsoft.azure.communication.chat.bot.contenttype metadat se vyžaduje jenom ve zprávě odeslané od uživatele do robota.

Pole podporovaných aktivit robota

Následující části popisují podporovaná pole aktivit robota pro toky mezi uživateli a toky mezi uživateli.

Tok mezi roboty a uživatelem

Pro toky mezi uživateli jsou podporována následující pole aktivit robota.

Aktivity

Zpráva
Psaní

Pole aktivit zpráv

Text
Attachments
AttachmentLayout
SuggestedActions
From.Name (Převedeno na Komunikační služby SenderDisplayName.)
ChannelData (Převedeno na komunikační služby Chat Metadata. Pokud jsou nějaké ChannelData hodnoty mapování objekty, serializují se ve formátu JSON a odesílají se jako řetězec.)

Tok uživatele k robotovi

Tato pole aktivit robota jsou podporovaná pro toky mezi uživateli.

Aktivity a pole

Zpráva
- Id (ID zprávy chatu služby Communication Services)
- TimeStamp
- Text
- Attachments
Aktualizace konverzací
- MembersAdded
- MembersRemoved
- TopicName
Aktualizace zprávy
- Id (Aktualizované ID chatové zprávy komunikační služby)
- Text
- Attachments
Odstranění zprávy
- Id (ID zprávy chatu odstraněné komunikační služby)
Událost
- Name
- Value
Psaní

Další běžná pole

Recipient.Id a Recipient.Name (ID uživatele chatu komunikačních služeb a zobrazované jméno)
From.Id a From.Name (ID uživatele chatu komunikačních služeb a zobrazované jméno)
Conversation.Id (ID vlákna chatu komunikačních služeb)
ChannelId (Chat komunikačních služeb, pokud je prázdný)
ChannelData (Metadata zpráv chatu služby Communication Services)

Vzory předání robota

Někdy robot nerozumí otázce nebo nemůže odpovědět na otázku. Zákazník se může v chatu zeptat, aby byl připojený k lidskému agentu. V těchto scénářích musí být vlákno chatu předáno z robota do lidského agenta. Aplikaci můžete navrhnout tak, aby přecháděla konverzaci z robota na člověka.

Zpracování komunikace mezi roboty

V některých případech použití je potřeba přidat dva roboty do stejného chatovacího vlákna, aby mohli poskytovat různé služby. V tomto scénáři možná budete muset zajistit, aby robot neodesílal automatizované odpovědi do zpráv jiného robota. Pokud se roboti nezpracují správně, může automatizovaná interakce mezi sebou vést k nekonečné smyčce zpráv.

Identitu uživatele komunikační služby odesílatele zprávy můžete ověřit ve vlastnosti aktivity From.Id . Zkontrolujte, jestli patří jinému robotovi. Pak proveďte požadovanou akci, která zabrání toku komunikace mezi roboty. Pokud tento typ scénáře vede k vysokému počtu volání, kanál chatu komunikační služby omezí požadavky a robot nemůže odesílat a přijímat zprávy.

Přečtěte si další informace o omezeních limitů.

Odstraňování potíží

Následující části popisují způsoby řešení běžných scénářů.

Kanál chatu nejde přidat.

Na portálu pro vývojáře Microsoft Bot Framework přejděte do> části Zasílání zpráv konfiguračního robota a ověřte, že je koncový bod správně nastavený.

Robot při odpovídání na zprávu dostane výjimku zakázáno.

Ověřte, že id a heslo aplikace Microsoftu robota jsou správně uložené v konfiguračním souboru robota, který nahrajete do webové aplikace.

Robota nejde přidat jako účastníka

Ověřte, že se ID komunikační služby robota používá správně, když se odešle požadavek na přidání robota do vlákna chatu.

Další kroky

Začínáme s chatem

Můžete také chtít:

Seznámení s koncepty chatu
Vysvětlení fungování cen pro chat

Sdílet prostřednictvím