Přidejte kopilota do mobilních a vlastních aplikací

Důležité

Schopnosti a funkce Power Virtual Agents jsou nyní součástí Microsoft Copilot Studio po významných investicích do generativní umělé inteligence a vylepšených integracích napříč Microsoft Copilot.

Některé články a snímky obrazovky mohou odkazovat na Power Virtual Agents, zatímco aktualizujeme dokumentaci a obsah školení.

Svého kopilota můžete připojit k vlastní aplikaci, aby uživatelé aplikace mohli s kopilotem interagovat 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í vašeho kopilota 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 bylo možné kopilota plně integrovat 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.
• Kopilot vytvořený v Copilot Studio, kterého chcete připojit ke své aplikaci.

Připojte svého kopilota k webové aplikaci

1. V Copilot Studio v navigační nabídce pod Nastavení vyberte Kanály.

2. Vyberte dlaždici Mobilní aplikace pro otevření konfiguračního okna.

3. 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ého kopilota 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, vaši vývojáři se kromě následujících pokynů mohou dozvědět více na Připojte svého robota ke kanálům Azure Bot Service.

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:

• Bot Framework Direct Line API
• Ověřování Direct Line
• Kontextové proměnné dostupné po předání
• Aktivita Microsoft Bot Framework

Načtení parametrů kopilota Copilot Studio

Chcete-li se připojit k kopilotovi, musíte získat název kopilota a koncový bod tokenu pro jeho identifikaci.

1. Zkopírujte název svého kopilota Copilot Studio.

   

2. V navigační nabídce pod Nastavení vyberte Kanály.

3. Vyberte Mobilní aplikaci.

   

4. Vedle položky Koncový bod tokenu vyberte možnost 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 s vaším kopilotem , 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 žádost úspěšná, token Direct Line bude vrácen spolu s časem ukončená platnosti a conversationId pro požadovaného kopilota. 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á ukázky z Ukázkového kódu konektoru, aby získal token Direct Line pro kopilota Copilot Studio.

/// <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žití Direct Line pro komunikaci s kopilotem

Po načtení tokenu Direct Line jste připraveni konverzovat se svým kopilotem Copilot Studio pomocí 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 pro zahájení konverzace a odesílání a přijem zpráv od kopilota Copilot Studio.

1. 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;
      }
   

2. 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",
              });
          }
      }
   

3. Získejte odpověď kopilota pomocí stejného token a conversationId. Načtené aktivity odpovědi Direct Line obsahují zprávy uživatele i kopilota. Aktivity odpovědí můžete filtrovat podle jména svého kopilota, abyste získali pouze zprávu s odpovědí kopilota.

      // 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

Možná budete muset přidat kód pro obnovení tokenu Direct Line, pokud vaše aplikace vede dlouhou konverzaci s kopilotem. 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

Parsovat datovou část konverzace z kopilota

Po zahájení konverzace s kopilotem 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áš kopilot automaticky odeslal systémové téma Pozdrav, když uživatel zahájí konverzaci, můžete odeslat aktivitu s Type=event a Name=startConversation.