Publicere en agent til mobilapps eller brugerdefinerede apps

Forbind en offentliggjort Copilot Studio-agent til din mobil- eller brugerdefinerede app, så brugerne kan interagere med agenten uden at forlade appen.

Vælg den integration, der passer til din app:

• Web-embed-kode: Tilføj den medfølgende chatgrænseflade til en webbaseret app.
• Direkte linje: Send og modtag meddelelser programmatisk fra en native app, en tilpasset webgrænseflade eller en adapter til en anden tjeneste.

Du kan få mere at vide om en separat SDK-baseret integration i Integrer web- eller lokale apps med SDK til Microsoft 365-agenter.

Forudsætninger

• En udgivet agent for Copilot Studio. Få mere at vide i Publicer og udrul din agent.
• Til C#-eksemplerne kræves et understøttet .NET SDK og NuGet-pakkerne Microsoft.Bot.Connector.DirectLine og Microsoft.Rest.ClientRuntime. Disse eksempler bruger System.Net.Http.Json og System.Text.Json.Serialization til token-svaret.
• Udviklingsværktøjer, der passer til din app. .NET-forudsætningerne gælder kun for C#-eksemplerne, ikke for alle integrationer.

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

For at oprette forbindelse til Azure Bot Service-kanaler kan du få mere at vide i Udgiv en agent til Azure Bot Service-kanaler.

Referencer

Instruktionerne i denne artikel bruger følgende referencer:

• Bot Framework Direct Line-API
• Direct Line-autentificering
• 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 Direct Line-token

For at starte en samtale med din agent, få et Direct Line-token ved at sende en GET-anmodning til det token-endpoint, du kopierede fra Copilot Studio. Dette endepunkt er Copilot Studio-token-endepunktet, ikke Direct Line-tokens/generate-endepunktet. Brug det returnerede token til efterfølgende Direct Line-anmodninger.

En Direct Line-token giver adgang til en samtale; det er ikke en slutbruger-login-token. Læg ikke en Direct Line-hemmelighed i browser- eller mobilapp-koden. Lær mere om Direct Line-autentificering.

GET <TokenEndpoint>

Hvis anmodningen lykkes, returnerer endepunktet et token, dets levetid i sekunder i expires_in, og en conversationId. Brug den returnerede levetid i stedet for at antage en fast udløbsperiode.

{
    "token": "<DirectLineToken>",
    "expires_in": 3600,
    "conversationId": "<ConversationId>"
}

Eksempel på tokenkode til direct line

Tilføj følgende metode og svartype til din applikationsklasse. Import System.Net.Http.Json og System.Text.Json.Serialization.

Metoden accepterer en HttpClient administreret af kalderen og genererer en undtagelse, hvis endepunktet ikke returnerer et brugbart token. HTTP- og JSON-fejl overføres til kalderen.

public static async Task<DirectLineToken> GetTokenAsync(
    HttpClient httpClient, string tokenEndpoint)
{
    var response = await httpClient.GetFromJsonAsync<DirectLineToken>(
        tokenEndpoint);

    if (response is null || string.IsNullOrWhiteSpace(response.Token))
    {
        throw new InvalidOperationException(
            "The token endpoint returned no Direct Line token.");
    }

    return response;
}

public sealed class DirectLineToken
{
    [JsonPropertyName("token")]
    public string Token { get; set; } = string.Empty;

    [JsonPropertyName("expires_in")]
    public int ExpiresIn { get; set; }

    [JsonPropertyName("conversationId")]
    public string ConversationId { get; set; } = string.Empty;
}

Brug Direct Line til at kommunikere med agenten

Efter at have hentet en token, brug Direct Line til at starte en samtale og sende og modtage aktiviteter. Lær mere i Bot Framework Direct Line API.

Følgende uddrag hører hjemme i den samme asynkrone metode i applikationsklassen, der indeholder GetTokenAsync. Import Microsoft.Bot.Connector.DirectLine og System.Linq. Erstat <TokenEndpoint> og <AgentName> med din agents værdier, og giv en app-specifik brugeridentifikator i stedet for <UserId>.

1. Få et token, initialiser et DirectLineClient, og start en samtale. Hold klient- og samtale-ID i scope for følgende operationer:

   using var httpClient = new HttpClient();
   var tokenResponse = await GetTokenAsync(httpClient, "<TokenEndpoint>");
   using var directLineClient = new DirectLineClient(tokenResponse.Token);
   
   var conversation =
       await directLineClient.Conversations.StartConversationAsync();
   string conversationId = conversation.ConversationId;
   string? watermark = null;
   string agentName = "<AgentName>";
   

2. Send en meddelelse til samtalen:

   string inputMessage = "Hello";
   await directLineClient.Conversations.PostActivityAsync(
       conversationId,
       new Activity
       {
           Type = ActivityTypes.Message,
           From = new ChannelAccount { Id = "<UserId>" },
           Text = inputMessage,
           TextFormat = "plain"
       });
   

3. Hent aktiviteter ved at bruge samme klient- og samtale-ID. Resultatet kan indeholde både bruger- og agentaktiviteter. Dette eksempel viser beskedaktiviteter fra det konfigurerede agentnavn:

   var response = await directLineClient.Conversations.GetActivitiesAsync(
       conversationId, watermark);
   watermark = response.Watermark ?? watermark;
   
   foreach (var activity in response.Activities.Where(activity =>
       activity.Type == ActivityTypes.Message &&
       string.Equals(activity.From?.Name, agentName, StringComparison.Ordinal)))
   {
       Console.WriteLine(activity.Text);
   }
   

   Gentag modtagelsesoperationen for at indsamle aktiviteter, der ankommer senere; en enkelt anmodning indeholder måske endnu ikke agentens svar. Send det seneste watermark på hver anmodning, og bevar den tidligere værdi, hvis svaret ikke giver et. Lær mere i Modtag aktiviteter fra botten.

   Beskedfilteret er kun til visning. Din app skal håndtere andre aktivitetstyper, inklusive Handoff-begivenheder, separat.

Opdater et Direct Line-token

Ved en længere samtale skal du opdatere tokenet, inden det udløber, og bruge den returnerede expires_in-værdi til at planlægge opdateringen. Et udløbet token kan ikke opdateres. Lær mere om Direct Line-autentificering.

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

var refreshedTokenResponse =
    await directLineClient.Tokens.RefreshTokenAsync();
using var refreshedClient = new DirectLineClient(refreshedTokenResponse.Token);

Brug refreshedClient til efterfølgende operationer med det eksisterende conversationId og vandmærke. Frigør klienter, når din app ikke længere har brug for dem.

Fortolk samtalenyttedata fra agenten

Når du har startet en samtale med agenten, bruger JSON-samtalenyttedataene den almindelige Microsoft Bot Framework Direct Line-aktivitet. Læs mere om Bot Framework Direct Line API.

Håndtering af afleveringsaktivitet

Hvis din applikation skal viderestille til en live agent-udbyder, skal du håndtere den overdragelsesaktivitet, der sendes, når en noden Transfer to agent kører. For at lære mere, se Eksempel på payload for overførselsbesked.

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.