Publicere en agent til mobilapps eller brugerdefinerede apps

Du kan finde din agent med en brugerdefineret app, så appens brugere kan arbejde sammen med agenten direkte fra din app.

I de fleste tilfælde er din brugerdefinerede app en mobilapp, der enten er en webbaseret app eller en oprindelig app. Det kan også være en adapter til andre tjenester, som din virksomhed kræver.

Der findes forskellige procedurer for oprettelse af forbindelse til din mobilapp, afhængigt af om din app er en webbaseret app eller en oprindelig app.

Det er forholdsvis ligetil at oprette forbindelse mellem din agent og en webbaseret app, da det involverer kopiere et kodestykke over i din app. Men både webbaserede apps og oprindelige apps eller brugerdefinerede apps kræver dog alligevel betydelig udviklingsekspertise for at kunne integrere agenten fuldt ud i din app. I denne artikel beskrives begge procedurer.

Forudsætninger

• .NET Core SDK version 2.1.
• NuGet-pakken Microsoft.Bot.Connector.DirectLine.
• En agent, der er oprettet i Copilot Studio, som du vil forbinde med din app.

Forbind din agent med en webbaseret app

1. I Copilot Studio, i navigationsmenuen, vælg Kanaler.

2. Vælg feltet Mobilapp for at åbne konfigurationsvinduet.

3. Kopiér koden under sektionen Webbaserede apps, og giv den til app-udviklerne, så de kan tilføje den til din webbaserede app.

   

Forbind din agent med en oprindelig eller brugerdefineret app

Hvis du vil oprette forbindelse til Azure Bot Service kanaler, skal du se Publicer en agent for at Azure Bot Service kanaler.

Referencer

Instruktionerne i dette dokument refererer til følgende kildemateriale:

• Bot Framework Direct Line-API
• Direct Line-godkendelse
• Kontekstvariabler, der er tilgængelige i forbindelse med aflevering
• Microsoft Bot Framework-aktivitet

Hent din agentparametre i Copilot Studio

Hvis du vil oprette forbindelse til den agent, du har oprettet, skal du hente agentens navn og tokenslutpunkt for at identificere det.

1. I Copilot Studio skal du gå til siden Overview for din agent og kopiere agentens navn.

2. Vælg Kanaler>Mobilapp.

3. På siden Mobilapp ud for Token-slutpunkt skal du vælge Kopiér. Du skal bruge dette slutpunkt til trinnet Hent Direct Line-token.

   Hent agentparametre.

Hent Direct Line-token

Hvis du vil starte en samtale med din agent, skal du have et Direct Line-token. Hent dette token ved at sende en GET-anmodning til det slutpunkt, der vises på skærmen Copilot Studio. Brug dette token som header for de næste kald til API'en til direkte linjer.

Eksempel:

GET <BOT TOKEN ENDPOINT>

Hvis anmodningen lykkes, returnerer slutpunktet et Direct Line-token, udløbstid og et conversationId for den anmodede agent.

Eksempel:

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

Eksempel på tokenkode til direct line

Følgende eksempel henter et Direct Line-token for en 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; }
}

Svarobjektet er det samme som den anmodning, GET du så tidligere.

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

Brug Direct Line til at kommunikere med agenten

Når du har hentet Direct Line-tokenet, er du klar til at føre en samtale med din Copilot Studio agent ved hjælp af Direct Line. Start en samtale, og send og modtag meddelelser ved at følge instruktionerne på Bot Framework Direct Line-API.

Følgende eksempel starter en samtale og sender og modtager meddelelser fra en Copilot Studio-agent.

1. Initialiser en DirectLineClient-forekomst med Direct Line-tokenet, og start en samtale:

      // 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. Når du er startet, kan du identificere og oprette forbindelse til hver samtale ved hjælp af kombinationen af token og conversationtId. Send en brugermeddelelse til en eksisterende samtale:

      // 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. Hent agentens svar ved hjælp af det samme token og conversationId. De hentede Direct Line-svaraktiviteter indeholder både brugerens og agentens meddelelser. Du kan filtrere svaraktiviteter efter din agents navn for kun at få agentens svarmeddelelse.

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

Opdater et Direct Line-token

Det kan være nødvendigt at tilføje kode for at opdatere dit Direct Line-token, hvis din applikation har en længerevarende samtale med din agent. Tokenet udløber, men kan opdateres, før det udløber. Du kan få mere at vide under Direct Line Authentication.

I følgende eksempel opdateres tokenet for en eksisterende Copilot Studio-samtale:

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

Fortolk samtalenyttedata fra agenten

Når du har startet en samtale med agenten, bruger JSON-samtalenyttedataene den almindelige Microsoft Bot Framework Direct Line-aktivitet. Du kan få mere at vide under Bot Framework Direct Line API.

Håndtering af afleveringsaktivitet

Hvis din applikation skal aflevere til en udbyder af live helpdesk-medarbejdere, skal du håndtere afleveringsaktiviteten. Afleveringsaktiviteten sendes, når noden Overfør til agent er nået. Du kan få mere at vide om nyttedataene for afleveringsaktivitet.

Udløs en velkomstmeddelelse

Hvis du vil have din agent til automatisk at sende emnet Hilsen system, når en bruger starter en samtale, skal du sende en aktivitet med Type=event og Name=startConversation.