Mobil veya özel uygulamaya yardımcı pilot ekleme

Makale
04/19/2024

Önemli

Power Virtual Agents yetenekleri ve özellikleri, Microsoft Copilot genelinde üretken yapay zekaya ve gelişmiş tümleştirmelere yapılan önemli yatırımların ardından artık Microsoft Copilot Studio'nun parçasıdır.

Bazı makalelerde ve ekran görüntülerinde, belgeler ve eğitim içeriği güncelleştirilirken Power Virtual Agents'a başvurulabilir.

Uygulama kullanıcılarının yardımcı pilot ile doğrudan uygulamanızın içinden etkileşim kurabilmesi için yardımcı pilotunuzu özel bir uygulamaya bağlayabilirsiniz.

Çoğu durumda, özel uygulamanız web tabanlı bir uygulama veya yerel bir uygulama ya da işinizin gerektirdiği diğer hizmetler için bağdaştırıcı olan bir mobil cihaz uygulamasıdır.

Uygulamanızın web tabanlı bir uygulama veya yerel bir uygulama olup olmadığına bağlı olarak mobil uygulamanıza bağlanmak için kullanılan farklı yordamlar vardır.

Yardımcı pilotunuzu web tabanlı bir uygulamaya bağlamak, kod parçacığını uygulamanıza kopyalamayı içerdiğinden nispeten basit bir işlemdir. Ancak web tabanlı uygulamalar ile yerel veya özel uygulamalar, yardımcı pilotu uygulamanıza tam olarak tümleştirmek için yüksek düzeyde geliştirici uzmanlığı gerektirir. Bu makalede her iki yordam da açıklanmaktadır.

Önkoşullar

.NET Core SDK sürüm 2.1.
NuGet paketi Microsoft.Bot.Connector.DirectLine.
Uygulamanıza bağlamak istediğiniz Copilot Studio'ta oluşturulan bir yardımcı pilot.

Yardımcı pilotunuzu web tabanlı bir uygulamaya bağlama

Copilot Studio'ta, gezinti menüsünde Ayarlar altında Kanallar'ı seçin.
Yapılandırma penceresini açmak için Mobil uygulama kutucuğunu seçin.
Web tabanlı uygulamalar bölümünün altındaki kodu kopyalayın ve web tabanlı uygulamanıza eklemek için bunu uygulama geliştiricilerinize sağlayın.

Yardımcı pilotunuzu yerel veya özel bir uygulamaya bağlama

İpucu

Bu bölümde bir mobil uygulamaya bağlanma açıklansa da aynı işlem IoT (Nesnelerin interneti) uygulamaları gibi özel veya yerel uygulamalar için de geçerlidir.

Amacınız Azure Bot Hizmeti kanallarına bağlanmaksa geliştiricileriniz buradaki yönergeleri izlemenin yanı sıra Botunuzu Azure Bot Hizmeti kanallarına bağlama bölümünde daha fazla bilgi edinebilir.

Önemli

Bu bölümdeki yönergeler geliştiricilerinizin veya sizin yazılım geliştirmenizi gerektirir. Bu; geliştirici araçları, yardımcı programlar ve IDE'ler ile ilgili üst düzey bilgiye sahip BT yöneticileri veya geliştiriciler gibi deneyimli BT uzmanlarına yöneliktir.

Kod örnekleri

Bu belgede kullanılan kod parçacıkları şunlardır:

Bağlayıcı örnek kodu

Başvurular

Bu belgedeki yönergeler aşağıdaki kaynak malzemeye başvurur:

Copilot Studio yardımcı pilot parametrelerinizi alma

Oluşturduğunuz yardımcı pilota bağlanmak için yardımcı pilotunuzu tanımlayan adını ve belirtecin uç noktasını geri almanız gerekir.

Copilot Studio uygulamasına yardımcı pilotunuzun adını kopyalayın.
Gezinti menüsünde, Ayarlar altında Kanallar'ı seçin.
Mobil uygulama'yı seçin.
Belirteç Uç Noktası'nın yanında Kopyala'yı seçin. Bu uç nokta, Direct Line belirtecini al adımında gereklidir.

Direct Line belirteci alma

Yardımcı pilot ile bir konuşma başlatmak için bir Direct Line belirtecine ihtiyacınız vardır. Bu belirteç Copilot Studio ekranında belirtilen uç noktaya AL isteğinde bulunarak elde edilebilir. Bu belirtecin, Directline API'sine yapılan sonraki çağrılar için başlık olarak kullanılması gerekir.

Örnek:

GET <BOT TOKEN ENDPOINT>

İstek başarılı olursa istenen yardımcı pilot için bir Direct Line belirteci, sona erme zamanı ve conversationId bilgisi döndürülür. Örnek:

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

Örnek kod örneği

Aşağıdaki örnekte, bir Copilot Studio yardımcı pilotuna ait Direct Line belirteci almak için Bağlayıcı örnek kodu'ndaki örnekler kullanılmıştır.

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

Yanıt nesnesi, daha önce gördüğümüz AL isteği ile aynıdır.

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

Direct Line'ı yardımcı pilotu ile iletişim kurmak için kullanma

Direct Line belirtecini aldıktan sonra, Direct Line kullanarak Copilot Studio yardımcı pilotunuzla bir konuşma yapmaya hazır olursunuz. Konuşmaya başlamak ve ileti gönderip almak için Bot Framework Direct Line API'si bölümündeki yönergeleri izleyin.

Aşağıdaki örnekte bir konuşma başlatmak ve Copilot Studio yardımcı pilotundan iletiler gönderip almak için Bağlayıcı örnek kodu'ndaki örnekler kullanılır.

Bir Direct Line belirteci ile bir DirectLineClient örneği başlatın ve bir konuşma başlatın:

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

Başlatıldıktan sonra, her konuşma token ve conversationtId birleşimi kullanılarak tanımlanabilir ve bağlanabilir. Var olan konuşmaya bir kullanıcı iletisi gönderin:

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

Aynı token ve conversationId'yi kullanarak yardımcı pilot yanıtını alın. Alınan Direct Line yanıt etkinlikleri hem kullanıcı hem de yardımcı pilotun iletilerini içerir. Yalnızca yardımcı pilotun yanıt iletisini almak için yanıt etkinliklerini yardımcı pilotun adına göre filtreleyebilirsiniz.

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

Direct Line belirtecini yenileme

Uygulamanızın yardımcı pilot ile uzun bir konuşması varsa Direct Line belirtecini yenilemek için kod eklemeniz gerekebilir. Belirtecin süresi dolar ancak süresi dolmadan önce yenilenebilir; Direct Line kimlik doğrulaması bölümünden daha fazla bilgi edinin.

Aşağıdaki örneklerde var olan Copilot Studio konuşması için belirteci yenilemek üzere Bağlayıcı örnek kodundaki örnekler kullanılır.

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

Konuşma yükünü yardımcı pilottan ayrıştırma

Yardımcı pilot ile bir konuşma başlattıktan sonra, konuşma JSON yükü standart Microsoft Bot Framework Direct Line etkinliği kullanır. Bot Framework Direct Line API'den daha fazla bilgi edinebilirsiniz.

Devir etkinliğini işleme

Uygulamanızın canlı temsilci sağlayıcısına devredilmesi gerekiyorsa devir etkinliğini işlemeniz gerekir. "Aracıya aktar" düğümü başlatıldığında devir etkinliği gönderilir. Devir etkinliği yükü hakkında daha fazla bilgi edinebilirsiniz.

Hoş geldiniz iletisi tetikleme

Kullanıcı bir konuşma başlattığında yardımcı pilotunuzun Selamlama sistemi konusunu otomatik olarak göndermesini isterseniz Type=event ve Name=startConversation ile bir etkinlik gönderebilirsiniz.

Aracılığıyla paylaş