Zveřejněte agent do mobilních nebo vlastních aplikací

Článek
12/09/2024

Svůj agent můžete propojit s vlastní aplikací, aby uživatelé aplikace mohli interagovat s agent přímo z vaší aplikace.

Ve většině případů je vaší vlastní aplikací aplikace pro mobilní zařízení, která je buď webovou aplikací, nebo nativní aplikací či adaptérem pro další služby, které vaše firma vyžaduje.

Existují různé postupy pro připojení k vaší mobilní aplikaci v závislosti na tom, zda je vaše aplikace webová aplikace nebo nativní aplikace.

Připojení agent k webové aplikaci je relativně jednoduché, protože zahrnuje zkopírování kódu fragment do vaší aplikace. Webové aplikace i nativní nebo vlastní aplikace však stále vyžadují značné odborné znalosti vývojářů, aby plně integrovaly agent do vaší aplikace. Oba postupy jsou popsány v tomto článku.

Předpoklady

.NET Core SDK verze 2.1.
Balíček Nuget Microsoft Bot ConnectorMicrosoft.Bot.Connector.DirectLine.
Agent vytvořený v Copilot Studio , který chcete připojit ke své aplikaci.

Připojte svůj agent k webové aplikaci

V Copilot Studio v navigační nabídce vyberte Kanály.
Vyberte dlaždici Mobilní aplikace pro otevření konfiguračního okna.
Zkopírujte kód pod sekcí Webové aplikace a poskytněte jej vývojářům své aplikace k přidání do vaší webové aplikace.

Připojte svůj agent k nativní nebo vlastní aplikaci

Tip

I když tato část popisuje, jak se připojit k mobilní aplikaci, stejný proces lze použít pro vlastní nebo nativní aplikace, jako jsou aplikace IoT (Internet of things).

Pokud je vaším cílem připojit se ke kanálům Azure Bot Service, kromě následujících pokynů se vaši vývojáři mohou dozvědět více na stránce Publikování agent na Azure Bot Service kanály.

Důležité

Pokyny v této části vyžadují vývoj softwaru od vás nebo vašich vývojářů. Je určený pro zkušené IT profesionály, jako jsou IT administrátoři nebo vývojáři, kteří dobře rozumí vývojářským nástrojům, utilitám a IDE.

Vzorky kódu

Fragmenty kódu použité v tomto dokumentu pocházejí z:

Ukázkový kód konektoru

Odkazy

Pokyny v tomto dokumentu odkazují na následující zdrojový materiál:

Načtěte parametry Copilot Studio agent

Chcete-li se připojit k agent, který jste vytvořili, musíte získat jméno agent a token koncový bod, abyste jej identifikovali.

V Copilot Studio přejděte na stránku Přehled svého agent a zkopírujte jméno svého agent.
Vyberte Kanály>Mobilní aplikace.
Na stránce Mobilní aplikace vedle položky Koncový bod tokenu vyberte Kopírovat. Tento koncový bod budete potřebovat v kroku Získat token Direct Line.

Získat token Direct Line

Chcete-li zahájit konverzaci se svým agent, potřebujete token Direct Line . Tento token lze získat odesláním požadavku GET na koncový bod uvedenou na obrazovce Copilot Studio. Tento token se pak musí použít jako hlavička pro následná volání rozhraní API přímé linky.

Příklad:

GET <BOT TOKEN ENDPOINT>

Pokud je požadavek úspěšný, bude vrácen Direct Line token, čas vypršení platnosti a ID konverzace pro požadovaný agent. Příklad:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Příklad ukázkového kódu

Následující příklad používá vzorky z ukázkového kódu konektoru k získání tokenu Direct Line pro Copilot Studio agent.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

Objekt odpovědi je stejný jako požadavek GET, který jsme viděli dříve.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Použijte Direct Line pro komunikaci s agent

Po načtení tokenu Direct Line jste připraveni konverzovat se svým Copilot Studio agent s Direct Line. Postupujte podle pokynů v Bot Framework Direct Line API pro zahájení konverzace a odesílání a přijímání zpráv.

Následující příklad používá ukázky z ukázkového kódu konektoru k zahájení konverzace a odesílání a přijímání zpráv z Copilot Studio agent.

Inicializujte instanci DirectLineClient pomocí tokenu Direct Line a zahajte konverzaci:

   // Use the retrieved token to create a DirectLineClient instance
   using (var directLineClient = new DirectLineClient(token))
   {
       var conversation = await directLineClient.Conversations.StartConversationAsync();
       string conversationtId = conversation.ConversationId;
   }

Po zahájení lze každou konverzaci identifikovat a propojit pomocí kombinace token a conversationtId. Odeslat uživatelskou zprávu do existující konverzace:

   // Use the retrieved token to create a DirectLineClient instance
   // Use the conversationId from above step
   // endConversationMessage is your predefined message indicating that user wants to quit the chat
   while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
   {
       using (var directLineClient = new DirectLineClient(token))
       {
           // Send user message using directlineClient
           // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
           await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
           {
               Type = ActivityTypes.Message,
               From = new ChannelAccount { Id = "userId", Name = "userName" },
               Text = inputMessage,
               TextFormat = "plain",
               Locale = "en-Us",
           });
       }
   }

Načtěte agent's odpověď pomocí stejného token a conversationId. Získané aktivity Direct Line odpověď obsahují zprávy uživatele i agent. Aktivity odpověď můžete filtrovat podle jména agent a získat pouze zprávu agent's odpověď.

   // Use the same token to create a directLineClient
   using (var directLineClient = new DirectLineClient(token))
   {
       // To get the first response set string watermark = null
       // More information about watermark is available at
       // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0

       // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
       ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);

       // update watermark from response
       watermark = response?.Watermark;

       // response contains set of Activity from both user and bot
       // To display bot response only, filter Activity.From.Name equals to your bot name
       List<Activity> botResponses = response?.Activities?.Where(x =>
                 x.Type == ActivityTypes.Message &&
                   string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();

       // Display botResponses
   }

Aktualizujte token Direct Line

Pokud vaše aplikace vede dlouhou konverzaci s agent, možná budete muset přidat kód pro obnovení tokenu Direct Line . Platnost tokenu vyprší, ale lze jej před vypršením obnovit; více se dozvíte v Autentizaci Direct Line.

Následující příklad používá ukázky z Ukázkového kódu konektoru, aby aktualizoval token pro stávající konverzaci Copilot Studio:

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Analyzujte obsah konverzace z agent

Po zahájení konverzace pomocí agent použije datová část JSON konverzace standardní aktivitu Microsoft Bot Framework Direct Line . Více se můžete dozvědět na Bot Framework Direct Line API.

Zvládněte předávací činnost

Pokud vaše aplikace musí být předána poskytovateli živého agenta, budete muset zvládnout předání. Aktivita předání je odeslána, když je zasažen uzel "Převod k agentovi". Můžete se dozvědět více o datové části předávací aktivity.

Aktivace uvítací zprávy

Pokud chcete, aby váš agent automaticky odeslal pozdrav systémové téma, když uživatel zahájí konverzaci, můžete odeslat aktivitu pomocí Type=event a Name=startConversation.

Sdílet prostřednictvím