Publikowanie pomocnika do kanałów usługi Azure Bot Service

Artykuł
11/20/2024

Copilota można połączyć z istniejącymi kanałami Azure Bot Service, co może być pomocne, jeśli chcesz połączyć swojego pomocnika z użytkownikami końcowymi na 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 zamierzasz połączyć się z niestandardową aplikacją opartą na sieci Web lub natywną aplikacją, deweloperzy mogą dowiedzieć się więcej o tym, w temacie Publikowanie pomocnika na urządzenia mobilne lub niestandardowe aplikacje.

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

Subskrypcja usługi Azure bot Service.
Usługa Azure bot Service bot z użyciem wersji 4 SDK.
.NET Core SDK wersja 2.1.
Pakiet NuGet Microsoft.Bot.Connector.DirectLine.
Pomocnik utworzony w Copilot Studio, którego chcesz połączyć z kanałem Azure Bot Service.
Dodawanie usługi pomocniczej do aplikacji mobilnej lub niestandardowej.

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 dokumentów:

Wdróż swojego bota na platformie Azure, aby uzyskać instrukcje dotyczące wdrażania usługi bota Azure Bot Service.
Kanały usługi Azure Bot Service umożliwiają łączenie się z jakimkolwiek kanałem obsługiwanym przez usługę Azure Bot Service.
Instrukcje dotyczące debugowania Azure Bot Service za pomocą emulatora są opisane w sekcji dotyczącej debugowania usługi Azure Bot Service.

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.

Skopiuj nazwę pomocnika w programie Copilot Studio.
W menu nawigacji w sekcji Ustawienia wybierz Kanały.
Wybierz kanał, z którym chcesz nawiązać połączenie. W tym scenariuszu użyto jako przykładu usługi Slack.
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.

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.

Twój bot usługi Azure Bot Service będzie musiał mapować i przekazywać konwersację z kanału usługi Azure Bot Service do konwersacji Direct Line z pomocnikiem Copilot Studio i odwrotnie.

Przykładowy kod

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

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

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. Pomocnik konwersacji Copilot Studio do obsługi odświeżania tokenów Direct Line jest zdefiniowana 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
}

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

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

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.

Udostępnij za pośrednictwem