Publisere en agent til mobilapplikasjoner eller egendefinerte apper

Artikkel
12/09/2024

Du kan koble agent til en egendefinert app, slik at brukerne av appen kan samhandle med agent 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.

Å koble agent til en nettbasert app er relativt enkelt, da det innebærer å kopiere en kodesnutt til appen din. Både nettbaserte apper og innebygde eller tilpassede apper krever imidlertid fortsatt betydelig utviklerekspertise for å integrere agent fullt ut i appen din. Begge prosedyrene beskrives i denne artikkelen.

Forutsetning

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

Koble agent til en nettbasert app

I Copilot Studio, på navigasjonsmenyen, velger du Kanaler.
Velg Mobilapp-flisen for å åpne konfigurasjonsvinduet.
Kopier koden under Nettbaserte apper-delen, og gi den til programutviklerne slik at de kan legge den til den nettbaserte appen din.

Koble agent til en innebygd eller tilpasset 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 ditt er å koble til Azure robot tjenestekanaler, kan utviklerne i tillegg til å følge instruksjonene Her, lære mer under Publisere en agent til Azure robot tjenestekanaler.

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:

Eksempelkode for kobling

Referanser

Instruksjonene i dette dokumentet refererer til følgende kildemateriale:

Hent parameterne dine Copilot Studio agent

For å koble til agent du bygde, må du hente navnet og tokenet til agent endepunkt for å identifisere det.

Gå Copilot Studio til Oversikt-siden til agent, og kopier navnet til agent.
Velg Kanaler>Mobilapp.
På siden Mobilapp, ved siden av Tokenendepunkt, velger du Kopier. Du trenger dette endepunktet for Hent Direct Line-token.

Hent Direct Line-token

For å starte en samtale med agent, 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 en conversationId for den forespurte agent. Eksempel:

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

Eksempel på eksempelkode

I eksemplet nedenfor brukes eksempler fra eksempelkoden for koblingen til å hente 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 vi så tidligere.

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

Bruk Direct Line til å kommunisere med agent

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

Eksemplet nedenfor bruker eksempler fra eksempelkoden for kobling til å starte en samtale og sende og motta meldinger fra en Copilot Studio agent.

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

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

Hent agent er svar ved å bruke samme token og conversationId. De hentede Direct Line svar aktivitetene inneholder både brukerens og agent-meldingene. Du kan filtrere aktivitetene svar etter navnet på agent for å få bare svar-meldingen til agent.

   // 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 tokenet Direct Line hvis programmet har en lang samtale med agent. 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

Analyser samtalenyttelasten fra agent

Når du har startet en diskusjon med agent, bruker JSON-nyttelasten for diskusjon standardaktiviteten Microsoft Bot Framework Direct Line . 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 agent skal sende hilsenen systememne automatisk når en bruker starter en samtale, kan du sende en aktivitet med Type=event og Name=startConversation.

Del via