Publikowanie agent w kanałach usługi Azure Bot Service

Artykuł
12/31/2024

Agenta można połączyć z istniejącymi kanałami Azure Bot Service, co może być pomocne, jeśli chcesz połączyć swojego agenta z użytkownikami końcowymi na kanałach Azure Bot Service.

Dodanie swoich agentów do kanałów usługi Azure Bot Service wymaga znacznej wiedzy specjalistycznej dostępnej dla deweloperów. Ten artykuł jest napisany dla administratorów IT i deweloperów, którzy mają doświadczenie w opracowywaniu i pisaniu kodu.

Wskazówka

Użytkownik nie musi korzystać z tej dokumentacji, aby dodać agenta Copilot Studio do witryny sieci internetowej, Facebooka lub 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 agenta 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.
Agent utworzony w programie Copilot Studio, który ma być połączony z kanałem usługi Azure Bot Service.
Publikowanie agenta w 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

Potrzebna jest usługa Azure Bot Service, która umożliwia przekazywanie konwersacji między agentem Copilot Studio i kanałami usługi 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.

Pobierz parametry Copilot Studio swojego agenta

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

Skopiuj nazwę agenta 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ć agenta z kanałem Azure Bot Service.

Zarządzanie sesjami konwersacji przy użyciu agenta Copilot Studio

Między kanałami usługi Azure bot i połączeniem Direct Line z Twoim agentem Copilot Studio może występować wiele konwersacji.

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 agentem Copilot Studio i odwrotnie.

Przykładowy kod

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

Na każdej nowej zewnętrznej konwersacji agenta kanału Azure Service Channel rozpocznij konwersację Copilot Studio. Aby uzyskać instrukcje dotyczące rozpoczynania nowej konwersacji z botem, zobacz temat Pobieranie tokenu Direct Line i korzystanie z Direct Line do komunikacji z agentem

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 utrzymać mapowanie zewnętrznych konwersacji w kanale usług Azure Bot Services na odpowiednie konwersacje z agentami Copilot Studio. Konwersacja z agentem Copilot Studio może być identyfikowana za pomocą programu i podłączona do dwóch właściwości: ConversationtId i 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. Agent 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 agent conversation
/// </summary>
public class PowerVirtualAgentsConversation
{
    public string ConversationtId { get; set; } // The Copilot Studio agent 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 agent
}

Podczas uruchamiania nowej rozmowy z agentem Copilot Studio należy dodać kluczową wartość pary (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) do tabeli mapowania.

// After new Copilot Studio agent 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ć pracę z istniejącą konwersacją, po otrzymaniu nowego komunikatu kanału zewnętrznego usługi Azure Bot Service pobierz istniejącą konwersację z tabeli mapowania, przekaż działanie dotyczące konwersacji zewnętrznej do swojego agenta Copilot Studio i wyświetl 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 agent and get response
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Retrieve agent conversation from mapping table
    // If not exists for the given external conversation ID, start a new Copilot Studio agent 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 Korzystanie z Direct Line do komunikacji z agentem, aby uzyskać informacje na temat sposobu uzyskiwania odpowiedzi agenta Copilot Studio. Po otrzymaniu odpowiedzi agent Copilot Studio należy skorzystać z informacji o sposobie analizy zawartości konwersacji przez agenta, aby dowiedzieć się jak przeanalizować odpowiedź na zewnętrzną odpowiedź kanału Azure Bot Services.

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