Publikowanie agenta w aplikacji mobilnej lub niestandardowej

Użytkownik może połączyć swoje agenty z aplikacją niestandardową, dzięki czemu użytkownicy aplikacji mogą współdziałać z tym agentem 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ą.

Połączenie agenta z aplikacją opartą na sieci web jest stosunkowo proste, ponieważ polega na skopiowaniu kodu przykładowego do aplikacji. Jednak zarówno aplikacje oparte na sieci Web, jak i aplikacje macierzyste lub niestandardowe wymagają znacznych umiejętności programistycznych, aby w pełni zintegrować agenta z 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 programie Copilot Studio, którego chcesz połączyć z aplikacją.

Łączenie swojego agenta z aplikacją opartą na sieci Web

1. W usłudze Copilot Studio wybierz pozycję Kanały w menu nawigacji.

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.

   

Łączenie agenta z aplikacją macierzystą lub niestandardową

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 Opublikowanie agenta do kanału usługi Azure Bot Service.

Odwołania

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

• Interfejs Direct Line API usługi Bot Framework
• Direct Line – uwierzytelnianie
• Zmienne kontekstowe dostępne po przekazaniu
• Aktywność Microsoft Bot Framework

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

1. W Copilot Studio przejdź do strony Przegląd agenta i skopiuj nazwę agenta.

2. Wybierz Kanały>Aplikacja mobilna.

3. 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ąć konwersację z agentem, potrzebny jest token 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, punkt końcowy zwraca token Direct Line, czas wygaśnięcia i identyfikator conversationId dla żądanego agenta.

Przykład:

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

Przykład kodu tokenu get Direct Line

Poniższy przykład pobiera token Direct Line dla agenta 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"
}

Używanie Direct Line do komunikowania się z agentem

Po pobraniu tokenu Direct line można przystąpić do konwersacji z agentem Copilot Studio przy użyciu Direct Line. Aby rozpocząć konwersację i wysyłać oraz otrzymywać wiadomości postępuj zgodnie z instrukcjami zawartymi w Interfejs Direct Line API Bot Framework, aby rozpocząć konwersację i wysłać i odebrać wiadomości.

Poniższy przykład rozpoczyna konwersację oraz wysyła i odbiera wiadomości od agenta programu 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. Pobieranie odpowiedzi agenta przy użyciu tych samych opcji token i conversationId. Pobrana odpowiedź dot czynności Direct Line zawiera w sobie zarówno wiadomości agenta, jak i użytkownika. Działania dotyczące odpowiedzi można filtrować według nazwy agenta, aby uzyskać tylko komunikat agenta.

      // 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ż token Direct Line

Jeśli aplikacja ma długotrwałą konwersację z agentem, może być konieczne dodanie kodu, aby odświeżyć token Direct Line. Token wygasa, ale może zostać odświeżony, zanim wygaśnie – więcej informacji na temat Uwierzytelniania Direct Line.

Poniższy przykład odświeża token dla istniejącej konwersacji programu 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

Analizuj zawartość konwersacji z agentem

Po rozpoczęciu konwersacji z agentem ładunek wejściowy JSON konwersacji używa standardowej działalności Microsoft Bot Framework Direct Line. Więcej informacji na ten temat można znaleźć w witrynie interfejsu API Direct Line Bot Framework.

Obsługa działania przekazania

Jeśli aplikacja musi zostać przekazana do dostawcy prawdziwego agenta, 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

Aby agent podczas rozpoczęcia konwersacji przez użytkownika automatycznie wysłał powitanie, można wysłać działanie za pomocą Type=event i Name=startConversation.