Publikowanie agent w aplikacjach mobilnych lub niestandardowych

Artykuł
12/09/2024

Możesz połączyć swój agent z aplikacją niestandardową, aby użytkownicy aplikacji mogli wchodzić w interakcje z agent bezpośrednio z poziomu Twojej aplikacji.

W większości przypadków Aplikacja niestandardowa to aplikacja na urządzenie przenośne, która jest aplikacją sieci Web lub macierzystym aplikacją albo kartą do innych usług, których wymaga twoja firma.

Istnieją różne procedury umożliwiające nawiązywanie połączeń z aplikacją mobilną w zależności od tego, czy dana aplikacja jest aplikacją sieciową czy natywną.

Połączenie agent z aplikacją internetową jest stosunkowo proste, ponieważ polega na skopiowaniu kodu wstawka do aplikacji. Jednak zarówno aplikacje internetowe, jak i aplikacje natywne lub niestandardowe nadal wymagają znacznej wiedzy programistycznej, aby w pełni zintegrować agent z Twoją aplikacją. Obie procedury zostały opisane w tym artykule.

Wymagania wstępne

.NET Core SDK wersja 2.1.
Pakiet NuGet Microsoft.Bot.Connector.DirectLine.
Agent utworzony w Copilot Studio miejscu, w którym chcesz połączyć się ze swoją aplikacją.

Połącz swój agent z aplikacją internetową

W usłudze Copilot Studio wybierz pozycję Kanały w menu nawigacji.
Wybierz kafelek Aplikacje mobilne, aby otworzyć okienko konfiguracji.
Skopiuj kod z sekcji Aplikacje oparte na sieci Web i przekaż go deweloperom aplikacji, aby dodać go do aplikacji sieciowej.

Połącz swój agent z aplikacją natywną lub niestandardową

Wskazówka

W tej sekcji opisano sposób łączenia się z aplikacją mobilną. Ten sam proces może dotyczyć niestandardowych lub natywnych aplikacji, takich jak aplikacje do obsługi IoT.

Jeśli Twoim celem jest nawiązanie połączenia z kanałami Azure Bot Service, oprócz wykonania instrukcji podanych tutaj, Twoi programiści mogą dowiedzieć się więcej na stronie Publikowanie kanałów od agent do Azure Bot Service.

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).

Przykłady kodu

Urywki kodu użyte w tym dokumencie pochodzą z programu:

Przykładowy kod łącznika

Odwołania

Instrukcje zawarte w tym dokumencie odwołują się do następujących materiałów źródłowych:

Pobierz swoje Copilot Studio agent parametry

Aby nawiązać połączenie z agent, który zbudowałeś, musisz pobrać nazwę i punkt końcowy tokenu agent, aby go zidentyfikować.

W Copilot Studio obszarze przejdź do strony Przegląd swojego agent i skopiuj nazwę swojego agent.
Wybierz Kanały>Aplikacja mobilna.
Na stronie Aplikacja mobilna obok pozycji Punkt końcowy tokenu wybierz pozycję Kopiuj. Musisz to zrobić punkt końcowy kroku Uzyskaj token Direct Line .

Pobierz token Direct Line

Aby rozpocząć rozmowę ze swoim agent, potrzebujesz tokena Direct Line . Token można uzyskać za pomocą żądania GET do punktu końcowego wskazanego na ekranie Copilot Studio. Token ten musi następnie zostać użyty jako nagłówek dla kolejnych wywołań interfejsu API kanału directline.

Przykład:

GET <BOT TOKEN ENDPOINT>

Jeśli żądanie zakończy się pomyślnie, zostanie zwrócony Direct Line token, czas wygaśnięcia i identyfikator konwersacji dla żądanego agent. Przykład:

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

Przykładowy kod

W poniższym przykładzie użyto przykładów z przykładowego kodu łącznika w celu uzyskania tokenu Direct Line dla elementu a Copilot Studio agent.

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

Obiekt odpowiedzi jest taki sam, jak wcześniej żądania GET.

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

Służy Direct Line do komunikowania się z agent

Po pobraniu tokena Direct Line możesz rozpocząć rozmowę z twoim Copilot Studio agent z Direct Line. Aby rozpocząć rozmowę oraz wysyłać i odbierać wiadomości, postępuj zgodnie z instrukcjami wyświetlanymi w interfejsie Bot Framework Direct Line API.

W poniższym przykładzie użyto przykładów z przykładowego kodu łącznika, aby rozpocząć konwersację oraz wysyłać i odbierać komunikaty z # Copilot Studio agent.

Zainicjuj wystąpienie DirectLineClient za pomocą tokenu Direct Line i rozpocznij konwersację:

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

Po rozpoczęciu każdej konwersacji można ją zidentyfikować i połączyć, korzystając z kombinacji token i conversationtId. Wyślij wiadomość użytkownika do istniejącej konwersacji:

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

Pobierz odpowiedź agent za pomocą tego samego token i conversationId. Pobrane Direct Line odpowiedź działania zawierają zarówno wiadomości użytkownika, jak i agent. Możesz filtrować odpowiedź aktywności według nazwy agent, aby uzyskać tylko wiadomość odpowiedź agent.

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

Odświeżanie tokenu Direct Line

Może być konieczne dodanie kodu w celu odświeżenia tokenu Direct Line , jeśli aplikacja ma długą konwersację z agent. Token wygasa, ale może zostać odświeżony, zanim wygaśnie; Więcej informacji w Uwierzytelnianie Direct Line.

W poniższym przykładzie użyto elementów z przykładowego kodu łącznika w celu odświeżenia tokenu Direct Line w istniejącej konwersacji 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

Analizowanie ładunku konwersacji z agent

Po rozpoczęciu konwersacji z agent ładunek JSON konwersacji używa działania standardowego Microsoft Bot Framework Direct Line . Więcej informacji można znaleźć w Interfejs API Bot Framework Direct Line.

Obsługa działania przekazania

Jeśli aplikacja musi zostać przekazana do dostawcy agenta na żywo, trzeba będzie obsłużyć działanie przekazania. Działanie przekazania jest wysyłane po przejściu do węzła „Przekaż do agenta”. Możesz dowiedzieć się więcej na temat ładunku działania przekazania.

Wyzwalanie wiadomości powitalnej

Jeśli chcesz, aby agent automatycznie wysyłał temat systemowy powitania, gdy użytkownik rozpoczyna rozmowę, możesz wysłać działanie za pomocą operatora Type=event i Name=startConversation.

Udostępnij za pośrednictwem