Publiser en agent på mobilapper eller egne apper

Du kan koble agenten til en egen app, slik at appens brukere kan samhandle med agenten direkte fra appen.

I de fleste tilfeller er den egendefinerte appen en mobilenhetsapp som enten er en nettbasert app eller en opprinnelig app. Det kan også være en adapter for andre tjenester som bedriften krever.

Det finnes ulike fremgangsmåter for å koble til mobilappen, avhengig av om appen er en nettbasert app eller en opprinnelig app.

Det er relativt enkelt å koble agenten til en nettbasert app, siden det innebærer at du kopierer en kodesnutt til appen. Både nettbaserte apper og innebygde eller egne apper krever likevel betydelig utviklingsekspertise for å integrere agenten fullt ut i appen din. Denne artikkelen beskriver begge prosedyrene.

Forhåndskrav

• .NET Core SDK versjon 2.1.
• NuGet-pakke Microsoft.Bot.Connector.DirectLine.
• En agent opprettet i Copilot Studio som du vil koble til appen din.

Koble agenten til en nettbasert app

1. I Copilot Studio, i navigasjonsmenyen, velg Kanaler.

2. Velg Mobilapp-flisen for å åpne konfigurasjonsvinduet.

3. Kopier koden under Nettbaserte apper-delen, og gi den til programutviklerne slik at de kan legge den til den nettbaserte appen din.

   

Koble agenten til en innebygd eller egendefinert app

Hvis du vil koble til Azure Bot Service kanaler, kan du se Publiser en agent for å Azure Bot Service kanaler.

Referanser

Instruksjonene i dette dokumentet refererer til følgende kildemateriale:

• Bot Framework Direct Line API
• Direkte linjeautentisering
• Kontekstvariabler tilgjengelig ved overlevering
• Aktivitet i Microsoft Bot Framework

Hent dine Copilot Studio-agentparametere

Hvis du vil koble til agenten du bygde, henter du agentens navn og tokenendepunkt for å identifisere det.

1. I Copilot Studio går du til Overview-siden til agenten din og kopierer agentens navn.

2. Velg Kanaler>Mobilapp.

3. På siden Mobilapp, ved siden av Tokenendepunkt, velger du Kopier. Du trenger dette endepunktet for Få Direct Line-token-trinnet.

   

Hent Direct Line-token

For å starte en samtale med agenten din, trenger du en Direct Line-token. Få dette tokenet ved å sende en GET-forespørsel til endepunktet som vises på Copilot Studio-skjermen. Bruk dette tokenet som topptekst for neste kall til API-en for direkte linje.

Eksempel:

GET <BOT TOKEN ENDPOINT>

Hvis forespørselen lykkes, returnerer endepunktet et Direct Line-token, utløpstid og en samtale-ID for den forespurte agenten.

Eksempel:

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

Få et eksempel på en Direct Line-tokenkode

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 GET forespørselen du så tidligere.

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

Bruk Direct Line til å kommunisere med agenten

Når du har hentet Direct Line-tokenet, er du klar til å ha en samtale med Copilot Studio agenten ved hjelp av Direct Line. For å starte en samtale og sende og motta meldinger, følg instruksjonene på Bot Framework Direct Line API.

Eksemplet nedenfor starter en samtale og sender og mottar meldinger 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 har startet, kan du identifisere og koble til hver samtale ved hjelp av kombinasjonen av token og conversationtId. Sende en brukermelding 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 å bruke det samme token og conversationId. De hentede Direct Line-svaraktivitetene inneholder både brukerens og agentens meldinger. Du kan filtrere svaraktiviteter etter navnet på agenten for å bare hente agentens svarmelding.

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

Oppdatere Direct Line-token

Du må kanskje legge til kode for å oppdatere Direct Line-tokenet hvis applikasjonen din har en lang samtale med agenten. Tokenet utløper, men kan oppdateres før det utløper. Hvis du vil ha mer informasjon, kan du se Direct Line Authentication.

Følgende eksempel oppdaterer 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

Analyser samtalenyttelasten fra agenten

Etter at du har startet en samtale med agenten, bruker JSON-nyttelasten for samtalen standard Microsoft Bot Framework Direct Line-aktiviteten. Hvis du vil ha mer informasjon, kan du se Bot Framework Direct Line API.

Håndter overføringsaktivitet

Hvis programmet må foreta overføring til en live agent-leverandør, må du håndtere overføringsaktiviteten. Overleveringsaktiviteten sendes når overføringsnoden til agenten nåes. Du kan finne ut mer om nyttelasten for overføringsaktiviteten.

Utløs en velkomstmelding

Hvis du vil at agenten din skal sende emnet hilsningssystemet automatisk når en bruker starter en samtale, sender du en aktivitet med Type=event og Name=startConversation.