Delen via

Publiceer een agent naar mobiele of aangepaste apps

  • Artikel

U kunt uw Verbinden- agent koppelen aan een aangepaste app, zodat de gebruikers van de app rechtstreeks vanuit uw app met de agent 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 agent met een webgebaseerde app is relatief eenvoudig. U hoeft hiervoor alleen maar de code fragment in uw app te kopiëren. Zowel webgebaseerde apps als native of aangepaste apps vereisen echter nog steeds aanzienlijke expertise van ontwikkelaars om agent volledig in uw app te integreren. Beide procedures worden beschreven in dit artikel.

Vereisten

Verbinden uw agent naar een webgebaseerde app

  1. Selecteer in Copilot Studio, in het navigatiemenu 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.

    Voeg agent toe aan de webgebaseerde applicatie.

Verbinden uw agent naar 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 Verbinden naar Azure Bot Service-kanalen te publiceren, moeten uw ontwikkelaars niet alleen de instructies hier volgen, maar kunnen ze ook meer te weten komen op Een agent publiceren naar Azure Bot Service-kanalen.

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:

Haal uw Copilot Studio agent-parameters op

Om Verbinden toe te voegen aan de agent die u hebt gebouwd, moet u de naam van uw agent en het token eindpunt ophalen om deze te identificeren.

  1. Navigeer in Copilot Studio naar de Overzichtpagina van uw agent en kopieer de naam van uw agent.

  2. Selecteer Kanalen>Mobiele app.

  3. 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.

    Haal agent-parameters op.

Direct Line-token ophalen

Om een gesprek te beginnen met je agent, heb je 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, vervaldatum en een conversationId voor de aangevraagde agent geretourneerd. Voorbeeld:

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

Voorbeeldcode

In het volgende voorbeeld worden voorbeelden uit de Connector-voorbeeldcode gebruikt om een Direct Line token voor een Copilot Studio agent te verkrijgen.

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

Gebruik Direct Line om te communiceren met de agent

Nadat u het Direct Line token hebt opgehaald, bent u klaar om een gesprek te voeren met uw Copilot Studio agent 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 Connector-voorbeeldcode gebruikt om een gesprek te starten en berichten te verzenden en ontvangen van a Copilot Studio agent.

  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 agent's respons op met dezelfde token en conversationId. De opgehaalde Direct Line respons-activiteiten bevatten zowel berichten van de gebruiker als van agent. U kunt respons-activiteiten filteren op de naam van uw agent om alleen het bericht agent's respons te ontvangen.

       // 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 heeft met agent. 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

Parse conversatie-payload van de agent

Nadat u een gesprek start met agent, 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 agent automatisch de begroeting systeemonderwerp verzendt wanneer een gebruiker een gesprek start, kunt u een activiteit verzenden met Type=event en Name=startConversation.