Dodawanie pomocnika do aplikacji mobilnej oraz niestandardowej

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

Użytkownik może połączyć swoich pomocników z aplikacją niestandardową, dzięki czemu użytkownicy aplikacji mogą współdziałać z tym pomocnikiem bezpośrednio z poziomu 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ą.

Łączenie pomocnika z aplikacją sieci Web jest bardzo proste, ponieważ polega na skopiowaniu wstawki kodu, który zostanie skopiowany do aplikacji. Jednak zarówno aplikacje oparte w sieci Web, jak i aplikacje macierzyste lub niestandardowe nadal wymagają specjalizacji deweloperów, aby w pełni zintegrować pomocnika w aplikacji. Obie procedury zostały opisane w tym artykule.

Wymagania wstępne

Łączenie pomocnika z aplikacją sieci Web

  1. W Copilot Studio w menu nawigacji w sekcji Ustawienia wybierz Kanały.

  2. Wybierz kafelek Aplikacje mobilne, aby otworzyć okienko konfiguracji.

  3. Skopiuj kod z sekcji Aplikacje oparte na sieci Web i przekaż go deweloperom aplikacji, aby dodać go do aplikacji sieciowej.

    Dodaj pomocnika do aplikacji opartej na sieci Web.

Łączenie pomocnika z aplikacjami natywnymi i niestandardowymi

Porada

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 zamierzasz połączyć się z kanałami usługi Azure Bot Service, musisz skorzystać z zawartych tutaj instrukcji, ale Twoi deweloperzy mogą dowiedzieć się więcej na ten temat w temacie Łączenie bota do kanału usługi 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:

Odwołania

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

Odzyskaj parametry Copilot Studio swojego pomocnika

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

  1. Skopiuj nazwę pomocnika w programie Copilot Studio.

    Pobierz nazwę pomocnika.

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

  3. Wybierz opcję Aplikacja mobilna.

    Kanał aplikacji mobilnej.

  4. Obok opcji Punkt końcowy tokenu wybierz opcję Kopiuj. Musisz to zrobić punkt końcowy kroku Uzyskaj token Direct Line .

    Pobieranie parametrów pomocnika.

Pobierz token Direct Line

Aby rozpocząć rozmowę z pomocnikiem, potrzebny jest Direct Line token. 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 jest pomyślne, zostanie zwrócone Direct Line token, czas wygaśnięcia i rozmówca dla żądanego pomocnika. Przykład:

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

Przykładowy kod

W następującym przykładzie przedstawiono przykładowy kod programu Connector w celu uzyskania tokenu Direct Line dla pomocnika Copilot Studio.

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

Korzystanie z Direct Line do komunikacji z pomocnikiem

Po zakończeniu pobierania tokenu Direct Line można rozpocząć Copilot Studio rozmowę z pomocnikiem 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 następującym przykładzie przedstawiono przykładowy kod programu Connector w celu rozpoczęcia rozmowy oraz wysyłania i odbierania wiadomości z pomocnika Copilot Studio.

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

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

  3. Pobierz odpowiedź pomocnika, używając tego samego token i conversationId. Pobrane działania Direct Line odpowiedzi zawierają komunikaty użytkownika i pomocnika. Działania związane z odpowiedziami można filtrować według nazwy pomocnika, aby otrzymać tylko komunikat z odpowiedzią pomocnika.

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

Jeśli w aplikacji jest trakcie rozmowy z pomocnikiem Direct Line, może być konieczne dodanie kodu w celu odświeżenia tokenu. 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

Ładuj rozmowę analizy konwersacji z pomocnika

Po rozpoczęciu konwersacji z pomocnikiem ładunek JSON konwersacji używa standardowego działania 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 pomocnik wysyłał automatycznie system powitania z temat momencie rozpoczynania rozmowy przez użytkownika, możesz wysłać działanie razem z Type=event i Name=startConversation.