Een copilot publiceren naar mobiele of aangepaste apps

Artikel
09/27/2024

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

.NET Core SDK versie 2.1.
Nuget-pakket Microsoft.Bot.Connector.DirectLine.
Een copilot gemaakt in Copilot Studio die u met uw app wilt verbinden.

Uw copilot verbinden met een webapp

Selecteer in Copilot Studio het navigatiemenu Kanalen.
Selecteer de tegel Mobiele app om het configuratievenster te openen.
Kopieer de code onder de sectie Webapps en geef deze aan uw app-ontwikkelaars om toe te voegen aan uw webgebaseerde app.

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 Een copilot publiceren naar Azure Bot Service-kanalen 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:

Connector voorbeeldcode

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.

Navigeer op Copilot Studiode pagina Overzicht van uw copiloot en kopieer de naam van uw copiloot.
Selecteer Kanalen>Mobiele app.
Selecteer op de pagina Mobiele app , naast Token eindpunt, de optie Kopiëren. U hebt dit eindpunt nodig voor de stap Direct Line-token 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 respons-object 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

Nadat u het Direct Line token hebt opgehaald, bent u klaar om een gesprek te voeren met uw Copilot Studio co-piloot met 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.

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

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

Haal de reactie van de copilot op met dezelfde combinatie van token en conversationId. De opgehaalde Direct Line respons-activiteiten bevatten zowel berichten van de gebruiker als van de copiloot. 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 het token te vernieuwen als uw toepassing een langdurig gesprek met de copiloot heeft. Direct Line 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

Nadat u een gesprek met de copiloot bent begonnen, gebruikt de JSON-payload van het gesprek de standaardactiviteit. Microsoft Bot Framework Direct Line 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.

Delen via