Share via

Copilot toevoegen aan mobiele en aangepaste apps

  • Artikel

Belangrijk

Power Virtual Agents-mogelijkheden en -functies maken nu deel uit van Microsoft Copilot Studio na aanzienlijke investeringen in generatieve AI en verbeterde integraties binnen Microsoft Copilot.

Sommige artikelen en schermopnamen verwijzen mogelijk naar Power Virtual Agents terwijl we de documentatie en trainingsinhoud bijwerken.

U kunt uw copilot verbinden met een aangepaste app, zodat de gebruikers van de app rechtstreeks vanuit uw app met de copilot kunnen communiceren.

In de meeste gevallen is uw aangepaste app een app voor mobiele apparaten (een webapp of native app of adapter voor andere services die uw bedrijf nodig heeft).

Er zijn verschillende procedures om verbinding te maken met uw mobiele app, afhankelijk van of uw app een webapp of een native app is.

Het verbinden van uw copilot met een webapp is relatief eenvoudig omdat u een codefragment in uw app moet kopiëren. Zowel webgebaseerde apps als native of aangepaste apps vereisen echter nog steeds aanzienlijke expertise van ontwikkelaars om de copilot volledig in de app te integreren. Beide procedures worden beschreven in dit artikel.

Vereisten

Uw copilot verbinden met een webapp

  1. Selecteer in Copilot Studio in het navigatiemenu onder Instellingen de optie Kanalen.

  2. Selecteer de tegel Mobiele app om het configuratievenster te openen.

  3. Kopieer de code onder de sectie Webapps en geef deze aan uw app-ontwikkelaars om toe te voegen aan uw webgebaseerde app.

    Copilot toevoegen aan webtoepassing.

Uw copilot verbinden met een native of aangepaste app

Fooi

Hoewel in dit gedeelte wordt beschreven hoe u verbinding kunt maken met een mobiele app, kan hetzelfde proces worden toegepast voor aangepaste of native apps, zoals IoT-apps (Internet of Things).

Als het uw doel is om verbinding te maken met Azure Bot Service-kanalen, kunnen uw ontwikkelaars naast de instructies in dit artikel de informatie in Uw bot met Azure Bot Service-kanalen verbinden gebruiken.

Belangrijk

Voor instructies in deze sectie is softwareontwikkeling van u of uw ontwikkelaars vereist. Deze sectie is bedoeld voor ervaren IT-professionals, zoals IT-beheerders of ontwikkelaars, die een gedegen kennis hebben van ontwikkelaarstools, hulpprogramma's en IDE's.

Codevoorbeelden

Codefragmenten die in dit document worden gebruikt, zijn afkomstig van:

Verwijzingen

De instructies in dit document verwijzen naar het volgende bronmateriaal:

Uw Copilot Studio-copilotparameters ophalen

Om verbinding te maken met de copilot die u hebt gebouwd, moet u de naam van uw copilot en het token-eindpunt ophalen om deze te identificeren.

  1. Kopieer de naam van uw copilot in Copilot Studio.

    Naam van copilot ophalen.

  2. Selecteer in het navigatiemenu onder Instellingen de optie Kanalen.

  3. Selecteer Mobiele app.

    Kanaal voor mobiele app.

  4. Selecteer naast Tokeneindpunt de optie Kopiëren. U hebt dit eindpunt nodig voor de stap Direct Line-token ophalen.

    Copilotparameters ophalen.

Direct Line-token ophalen

Als u een gesprek wilt beginnen met uw copilot, hebt u een Direct Line-token nodig. Dit token kan worden verkregen door een GET-verzoek te doen aan de eindpunt aangegeven in het Copilot Studio-scherm. Dit token moet vervolgens worden gebruikt als header voor volgende aanroepen van de directline API.

Voorbeeld:

GET <BOT TOKEN ENDPOINT>

Als het verzoek succesvol is, worden een Direct Line-token, verlooptijd en een conversationId geretourneerd voor de aangevraagde copilot. Voorbeeld:

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

Voorbeeldcode

In het volgende voorbeeld worden voorbeelden uit de Voorbeeldcode voor connectors gebruikt om een Direct Line-token op te halen voor een Copilot Studio-copilot.

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

Het responsobject is hetzelfde als de GET-aanvraag die we eerder zagen.

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

Direct Line gebruiken om met de copilot te communiceren

Na het ophalen van de Direct Line-token, bent u klaar om een gesprek te voeren met uw Copilot Studio-copilot via Direct Line. Volg de instructies in Bot Framework Direct Line API om een gesprek te beginnen en berichten te verzenden en ontvangen.

In het volgende voorbeeld worden voorbeelden uit de voorbeeldcode voor connectors gebruikt om een gesprek te beginnen en berichten te verzenden en ontvangen van een Copilot Studio-copilot.

  1. Initialiseer een DirectLineClient-exemplaar met de Direct Line-token en start een gesprek:

       // 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. Eenmaal gestart, kan elk gesprek worden geïdentificeerd en verbonden met behulp van de combinatie van token en conversationtId. Stuur een gebruikersbericht naar een bestaand gesprek:

       // 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. Haal de reactie van de copilot op met dezelfde combinatie van token en conversationId. De opgehaalde Direct Line-responsactiviteiten bevatten berichten van zowel de gebruiker als de copilot. U kunt responsactiviteiten filteren op de naam van uw copilot om alleen het reactiebericht van de copilot te krijgen.

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

Direct Line-token vernieuwen

Mogelijk moet u code toevoegen om de Direct Line-token te vernieuwen als uw toepassing een langdurig gesprek heeft met de copilot. De token verloopt, maar kan worden vernieuwd voordat deze verloopt. Meer informatie is te vinden in Direct Line-verificatie.

In het volgende voorbeeld worden voorbeelden uit de voorbeeldcode voor connectors gebruikt om het token voor een bestaand Copilot Studio-gesprek te vernieuwen.

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

Nettolading van gesprek van de copilot parseren

Na het starten van een gesprek met de copilot, maakt de JSON-nettolading van het gesprek gebruik van de standaard Microsoft Bot Framework Direct Line-activiteit. Ga voor meer informatie naar Bot Framework Direct Line API.

Overdrachtsactiviteit afhandelen

Als uw toepassing moet worden overgedragen aan een live agent, moet u de overdrachtsactiviteit afhandelen. Overdrachtsactiviteit wordt verzonden wanneer het knooppunt Overdragen aan agent wordt bereikt. U kunt meer informatie over de nettolading van de overdrachtsactiviteit vinden.

Een welkomstbericht activeren

Als u wilt dat uw copilot automatisch het systeemonderwerp Begroeting stuurt wanneer een gebruiker een gesprek start, kunt u een activiteit sturen met Type=event en Name=startConversation.