Dodawanie pomocnika Copilot Studio do kanałów usługi Azure Bot Service

  • Artykuł

Ważne

Możliwości i funkcje Power Virtual Agents są teraz częścią Microsoft Copilot Studio w wyniku znacznych inwestycji w generatywną AI i poprawioną integracje z Microsoft Copilot.

Niektóre artykuły i zrzuty ekranów mogą odwoływać się do Power Virtual Agents podczas aktualizowania dokumentacji i zawartości szkoleniowej.

Możesz połączyć pomocnika z istniejącymi kanałami usługi Azure Bot Service. To może być pomocne, jeśli użytkownik chce połączyć pomocnika z użytkownikami końcowymi w kanałach Azure Bot Service.

Dodawanie pomocnika do kanałów Azure Bot Service wymaga pewnej wiedzy dewelopera. Ten artykuł jest napisany dla administratorów IT i deweloperów, którzy mają doświadczenie w opracowywaniu i pisaniu kodu.

Porada

Nie trzeba śledzić tego dokumentu, aby dodać pomocnika Copilot Studio do witryny internetowej, serwisu Facebook lub aplikacji Microsoft Teams. Jeśli celem jest połączenie z niestandardową aplikacją sieci Web lub aplikacją natywną, deweloperzy mogą dowiedzieć się więcej w temacie Dodawanie pomocnika do aplikacji mobilnych i niestandardowych.

Ważne

Instrukcje zawarte w tej sekcji wymagają opracowania oprogramowania przez użytkownika lub deweloperów. Jest ono przeznaczone dla doświadczonych specjalistów branży IT, takich jak administratorzy lub deweloperzy, którzy mają solidną wiedzę na temat narzędzi deweloperskich oraz zintegrowanych środowisk projektowych (IDE).

Wymagania wstępne

Przykłady kodu

Elementy kodu użyte w tym dokumencie pochodzą z przykładowego kodu przekaźnika bota.

Odwołania

Instrukcje zawarte w tym dokumencie odwołują się do następujących czynności:

Tworzenie lub korzystanie z istniejącej usługi Azure Bot Service

Musisz mieć usługę Azure Bot Service, która umożliwia przekazywanie konwersacji między pomocnikiem Copilot Studio i kanałami Azure Bot Service.

Diagram przekaźnika bot.

Przykładowy kod bota przekazującego to dobry punkt wyjścia, jeśli użytkownik nie ma istniejącej usługi Azure Bot Service. Jest utworzony na bazie przykładowego kodu bota Microsoft Bot Framework, który można skompilować i wdrożyć w usłudze Azure Bot Service. Przykładowy kod jest przeznaczony do użycia jako punkt wyjścia i nie jest przeznaczony do użycia bezpośrednio w produkcji. Trzeba będzie dodać kod i zoptymalizować go, aby odpowiadał wymaganiom firmy.

Jeśli usługa Azure Bot Service bot już istnieje, należy dodać łącznik Copilot Studio i kod, aby zarządzać sesjami konwersacji. Następnie można wdrożyć składnik bota na platformie Azure Bot Services i połączyć się ze kanałami za pomocą usługi Azure Portal.

Pobieranie parametrów pomocnika Copilot Studio

Aby połączyć się z pomocnikiem utworzonym w Copilot Studio, należy pobrać nazwę i token punktu końcowego pomocnika.

  1. Skopiuj nazwę pomocnika w programie Copilot Studio.

    Pobierz nazwę bota.

  2. W menu nawigacji w sekcji Ustawienia wybierz Kanały.

  3. Wybierz kanał, z którym chcesz nawiązać połączenie. W tym scenariuszu użyto jako przykładu usługi Slack.

    Kanał Slack.

  4. Aby skopiować i zapisać wartość Punkt końcowy tokenu, wybierz opcję Kopiuj. Twój punkt końcowy trzeba musiał łączyć pomocnika z kanałem Azure Bot Service.

    Pobierz parametry swojego bota.

Zarządzanie sesjami rozmowy przy użyciu pomocnika Copilot Studio

Mogą być prowadzone liczne konwersacje między kanałami Azure Bot Service i połączeniem Direct Line z pomocnikiem Copilot Studio.

Bot Azure Bot Service będzie potrzebny do mapowania i przekazywania rozmowy z kanału Azure Bot Service do połączenia Direct Line z pomocnikiem Copilot Studio i na odwrót.

Przykładowy kod

W poniższym przykładzie użyto elementów z przykładowego kodu bota przekazującego.

  1. W przypadku każdego nowego zewnętrznego kanału usługi Azure Bot Service, rozpocznij rozmowę z pomocnikiem Copilot Studio. Zobacz: Pobierz Direct Line token i użyj do Direct Line komunikowania się z pomocnikiem w celu uzyskania instrukcji dotyczących rozpoczynania nowej rozmowy z botem.

    using (var httpRequest = new HttpRequestMessage())
{   
    httpRequest.Method = HttpMethod.Get;
    UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
    httpRequest.RequestUri = uriBuilder.Uri;
    using (var response = await s_httpClient.SendAsync(httpRequest))
    {
        var responseString = await response.Content.ReadAsStringAsync();
        string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
    }
}

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

     // 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. Aby zarządzać wieloma sesjami, należy zachować mapowanie zewnętrznych konwersacji w kanałach usługi Azure Bot Service na odpowiednie konwersacje pomocnika Copilot Studio w sieci. Rozmowa Copilot Studio z pomocnikiem może być identyfikowana i połączona z dwiema właściwościami: ConversationtId oraz Token.

    Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();

    Aby zarządzać cyklem rozmowy, należy odświeżyć tokeny Direct Line lub wyczyścić konwersacje. Dowiedz się więcej o odświeżaniu tokenu w Odświeżaniu tokenu Direct Line. Rozmowa Copilot Studio z pomocnikami obsługująca te, które są zdefiniowane w następujący sposób:

    /// <summary>
/// Data model class for Copilot Studio copilot conversation
/// </summary>
public class PowerVirtualAgentsConversation
{
    public string ConversationtId { get; set; } // The Copilot Studio copilot conversation ID retrieved from step 1

    public string Token { get; set; } // The DirectLine token retrieved from step 1

    public string WaterMark { get; set; } // Identify turn in a conversation

    public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh

    public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to copilot
}

  3. Podczas uruchamiania nowej rozmowy pomocnika Copilot Studio dodaj kluczową parę wartości (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) do tabeli mapowania.

    // After new Copilot Studio copilot conversation starts
ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
  {
    Token = token,
    ConversationtId = conversationId,
    WaterMark = null,
    LastConversationUpdateTime = DateTime.Now,
    LastTokenRefreshTime = DateTime.Now,
  };

  4. Aby kontynuować istniejącą rozmowę, po otrzymaniu nowego zewnętrznego komunikatu kanału Azure Bot Service, należy pobrać istniejącą rozmowę z tabeli mapowania, przekazać działanie rozmowy zewnętrznej do pomocnika Copilot Studio i uzyskać odpowiedź.

    W poniższym przykładzie pokazano przekazywanie konwersacji poprzez zastąpienie metody ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken) method

    // Invoked when a message activity is received from the user
// Send the user message to Copilot Studio copilot and get response
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Retrieve copilot conversation from mapping table
    // If not exists for the given external conversation ID, start a new Copilot Studio copilot conversation
    ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
            currentConversation : /*await StartBotConversationAsync(externalCID)*/;

    // Create DirectLine client with the token associated to current conversation
    DirectLineClient client = new DirectLineClient(currentConversation.Token);

    // Send user message using directlineClient
    await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
    {
      Type = DirectLineActivityTypes.Message,
      From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
      Text = turnContext.Activity.Text,
      TextFormat = turnContext.Activity.TextFormat,
      Locale = turnContext.Activity.Locale,
    });

    // Update LastConversationUpdateTime for session management
    currentConversation.LastConversationUpdateTime = DateTime.Now;
}

  5. Zobacz Używanie Direct Line do komunikacji z pomocnikiem, aby dowiedzieć się, jak uzyskać odpowiedź pomocnika Copilot Studio. Po otrzymaniu odpowiedzi pomocnika Copilot Studio zapoznaj się z tematem Analizowanie ładunku konwersacji z poziomu pomocnika, aby dowiedzieć się, jak przeanalizować odpowiedź na zewnętrzną odpowiedź kanału Azure Bot Service.

Przykład analizy odpowiedzi można znaleźć w przykłądowym kodzie bota przekaźnika ResponseConverter.cs.

Wdróż na platformie Azure Bot Service

Po zainstalowaniu bota przekaźnikowego Azure Bot Service należy wdrożyć bota do usługi Azure Bot Service.

Konfigurowanie bota na kanale usługi Azure Bot Service

Użytkownik może skonfigurować kanały, z którymi ma się połączyć program, logując się do usługi Azure Portal i wybierając grupę zasobów usługi Azure Bot Service, która została wdrożona na stronie. Wyświetlanie poszczególnych instrukcji dotyczących każdego kanału znajdziesz w kanałach usługi Azure Bot Service.