Publicere en agent til mobilapps eller brugerdefinerede apps

2025-06-20

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 app til en mobilenhed og er enten en webbaseret app eller en oprindelig app eller kort til andre tjenester, som din virksomhed har brug for.

Der er forskellige procedurer for at oprette forbindelse til mobilappen, afhængigt af om appen 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. Begge procedurer er beskrevet i denne artikel.

Forudsætninger

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

Forbind din agent med en webbaseret app

Vælg Kanaler i navigationsmenuen i Copilot Studio.
Vælg feltet Mobilapp for at åbne konfigurationsvinduet.
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

Tips

Dette afsnit indeholder en beskrivelse af, hvordan du forbinder til en mobilapp, men den samme proces kan dog også anvendes til brugerdefinerede eller oprindelige apps, f.eks. IoT-apps (Tingenes internet).

Hvis dit mål er at oprette forbindelse til Azure Bot Service-kanaler, kan dine udviklere, udover at følge instruktionerne her, få mere at vide her: Publicere en agent til Azure Bot Service-kanaler.

Vigtige oplysninger

Instruktionerne i dette afsnit kræver udvikling af software fra dig eller dine udviklere. Det er udviklet til erfarne IT-medarbejdere, såsom IT-administratorer eller udviklere, der har en solid forståelse for udviklerværktøjer, værktøjer og IDE'er.

Referencer

Instruktionerne i dette dokument refererer til følgende kildemateriale:

Hent dine Copilot Studio-agentparametre

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

Gå i Copilot Studio til oversigtssiden for din agent, og kopiér navnet på din agent.
Vælg Kanaler>Mobilapp.
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 Direct Line-token

Hvis du vil starte en samtale med din agent, skal du bruge et Direct Line-token. Dette token kan angives ved at anmode den bruger, der slutpunkt GET, på Copilot Studio skærmen. Dette token skal derefter bruges som header for efterfølgende kald til directline-API'en.

Eksempel:

GET <BOT TOKEN ENDPOINT>

Hvis anmodningen lykkes, returneres 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 GET-forespørgsel, vi 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 med Direct Line. Følg instruktionerne i Bot Framework Direct Line-API for at starte en samtale og sende og modtage meddelelser.

Følgende eksempel starter en samtale og sender og modtager meddelelser 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;
   }

Når en samtale er startet, kan hver samtale identificeres og forbindes 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",
           });
       }
   }

Hent agentens svar ved hjælp af 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 Direct Line-tokenet, hvis der er tale om en længerevarende samtale med agenten. Tokenet udløber, men kan opdateres, før det udløber. Få mere at vide i Direct Line-godkendelse.

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 samtalens JSON-nyttedata standardaktiviteten for Microsoft Bot Framework Direct Line. Du kan få mere at vide på 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. Der sendes en afleveringsaktivitet, når noden "Overførsel til medarbejder" rammes. Du kan få mere at vide om nyttedataene for afleveringsaktivitet.

Udløs en velkomstmeddelelse

Hvis du ønsker, at din agent skal sende en hilsen til systememnet automatisk, når en bruger starter en samtale, kan du sende en aktivitet med Type=event og Name=startConversation.