Legge til en kopilot i mobilapper og egendefinerte apper

  • Artikkel

Viktig!

Power Virtual Agents-funksjoner er nå en del av Microsoft Copilot Studio etter betydelige investeringer i generativ kunstig intelligens og forbedrede integreringer på tvers av Microsoft Copilot.

Enkelte artikler og skjermbilder kan henvise til Power Virtual Agents når vi oppdaterer dokumentasjons- og opplæringsinnhold.

Du kan koble kopiloten til en egendefinert app slik at appens brukere kan samhandle med kopiloten direkte fra appen.

I de fleste tilfeller er den egendefinerte appen en mobilenhetsapp som enten er en nettbasert app eller en innebygd app eller en adapter til andre tjenester som virksomheten krever.

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

Det er relativt enkelt å koble kopiloten til en nettbasert app, siden det innebærer at du kopierer en kodesnutt til appen. Både nettbaserte apper og innebygde eller egendefinerte apper krever likevel betydelig utviklingsekspertise for at kopiloten skal kunne integreres fullt ut i appen din. Begge prosedyrene beskrives i denne artikkelen.

Forutsetning

Koble kopiloten din til en nettbasert app

  1. Velg Kanaler under Innstillinger på navigasjonsmenyen i Copilot Studio.

  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.

    Legg til kopiloten i et nettbasert program.

Koble kopiloten til en innebygd eller egendefinert app

Tips

Selv om denne delen beskriver hvordan du kobler til en mobilapp, kan den samme prosessen brukes for tilpassede eller innebygde apper, for eksempel IoT-apper (Tingenes Internett).

Hvis målet er å koble til Azure Bot Service-kanaler, kan utviklerne dine – i tillegg til å følge instruksjonene her – lære mer på Koble roboten din til Azure Bot Service-kanaler.

Viktig

Instruksjonene i denne delen krever programvareutvikling fra deg eller utviklerne. Den er beregnet på erfarne IT-eksperter, for eksempel IT-administratorer eller utviklere som har en solid forståelse av utviklerverktøy, og integrerte utviklingsmiljøer (IDE).

Kodeeksempler

Kodesnutter som brukes i dette dokumentet, er fra følgende steder:

Referanser

Instruksjonene i dette dokumentet refererer til følgende kildemateriale:

Hent parameterne for Copilot Studio-kopiloten

Hvis du vil koble til kopiloten du har bygd, må du hente kopilotens navn og tokenendepunktet for å identifisere den.

  1. Kopier navnet på kopiloten i Copilot Studio.

    Hent navnet på kopiloten.

  2. Velg Kanaler under Innstillinger på navigasjonsmenyen.

  3. Velg Mobilapp.

    Mobilappkanal.

  4. Velg Kopier ved siden av Tokenendepunkt. Du trenger dette endepunktet for Hent Direct Line-token.

    Hent parameterne for kopiloten.

Hent Direct Line-token

Hvis du vil starte en samtale med kopiloten, trenger du et Direct Line-token. Du kan hente dette tokenet ved å sende en GET-forespørsel til endepunkt som angis på Copilot Studio-skjermen. Dette tokenet må deretter brukes som overskrift for påfølgende kall til direktelinje-API.

Eksempel:

GET <BOT TOKEN ENDPOINT>

Hvis forespørselen er vellykket, returneres et Direct Line-token, utløpstid og conversationId for den forespurte kopiloten. Eksempel:

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

Eksempel på eksempelkode

Eksemplet nedenfor bruker eksempler fra Eksempelkode for kontakt til å hente et Direct Line-token for en Copilot Studio-kopilot.

/// <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 vi så tidligere.

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

Bruk Direct Line til å kommunisere med kopiloten

Etter at du har hentet Direct Line-tokenet, er du klar til å ha en samtale med Copilot Studio-kopiloten med Direct Line. Du kan starte en samtale og sende og motta meldinger ved å følge instruksjonene på Bot Framework Direct Line API.

Følgende eksempel bruker eksempler fra Eksempelkode for kobling for å starte en samtale og sende og motta meldinger fra en Copilot Studio-kopilot.

  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. Etter at du har startet en samtale, kan den identifiseres og kobles sammen 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 svaret til kopiloten med samme token og conversationId. De hentede Direct Line-svaraktivitetene inneholder meldingene for både bruker og kopilot. Du kan filtrere svaraktiviteter med navnet på kopiloten for å få bare kopilotens 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

Det kan hende du må legge til kode for å oppdatere Direct Line-tokenet hvis appen har en lang samtale med kopiloten. Tokenet utløper, men kan oppdateres før det utløper. Finn ut mer under Direct Line-godkjenning.

Eksemplet nedenfor bruker eksempler fra Eksempelkode for kobling for å oppdatere 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

Del opp samtalenyttelasten fra kopiloten

Etter at du har startet en samtale med kopiloten, bruker JSON-nyttelasten for samtalen standard Microsoft Bot Framework Direct Line-aktivitet. Du kan finne ut mer under 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. Overføringsaktivitet sendes når noden «Overfør til agent» er nådd. Du kan finne ut mer om nyttelasten for overføringsaktiviteten.

Utløs en velkomstmelding

Hvis du vil at kopiloten din skal sende systememnet Hilsen automatisk når en bruker starter en samtale, kan du sende en aktivitet med Type=event og Name=startConversation.