Een agent publiceren op mobiele of aangepaste apps

U kunt uw agent verbinden met 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 op mobiele apparaten die een web-app of een systeemeigen app is. Het kan ook een adapter zijn naar andere services die uw bedrijf nodig heeft.

Er bestaan verschillende procedures voor het maken van verbinding met uw mobiele app, afhankelijk van of uw app een web-app of een systeemeigen app is.

Het verbinden van uw agent 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 agent volledig in de app te integreren. In dit artikel worden beide procedures beschreven.

Prerequisites

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

Uw agent verbinden met een webapp

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.

   

Uw agent verbinden met een native of op maat gemaakte app

Als u verbinding wilt maken met Azure Bot Service kanalen, raadpleegt u Publiceer een agent naar Azure Bot Service kanalen.

Verwijzingen

De instructies in dit document verwijzen naar het volgende bronmateriaal:

• Direct Line-API van Bot Framework
• Direct Line-authenticatie
• Contextvariabelen beschikbaar bij overdracht
• Activiteit van Microsoft Bot Framework

Verkrijg uw parameters voor de Copilot Studio-agent

Als u verbinding wilt maken met de agent die u hebt gemaakt, haalt u de naam en het tokeneindpunt van uw agent op om deze te identificeren.

1. Ga in Copilot Studio naar de pagina Overview 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.

   

Direct Line-token ophalen

Als u een gesprek wilt beginnen met uw agent, hebt u een Direct Line-token nodig. Haal dit token op door een GET-aanvraag te verzenden naar het eindpunt dat wordt weergegeven in het scherm Copilot Studio. Gebruik dit token als de header voor de volgende aanroepen naar de Direct Line API.

Voorbeeld:

GET <BOT TOKEN ENDPOINT>

Als de aanvraag slaagt, retourneert het eindpunt een Direct Line-token, een vervaltijd en een conversationId voor de aangevraagde agent.

Voorbeeld:

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

Voorbeeld van code voor direct line-token ophalen

In het volgende voorbeeld wordt een Direct Line-token opgehaald voor een 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; }
}

Het antwoordobject is hetzelfde als de GET aanvraag die u eerder hebt gezien.

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

Direct Line gebruiken om met de agent te communiceren

Nadat u het Direct Line token hebt opgehaald, bent u klaar om een gesprek te voeren met uw Copilot Studio-agent met behulp van Direct Line. Volg de instructies op Bot Framework Direct Line API om een gesprek te beginnen en berichten te verzenden en te ontvangen.

In het volgende voorbeeld wordt een gesprek gestart en worden berichten verzonden en ontvangen van een Copilot Studio-agent.

1. Initialiseer een DirectLineClient-exemplaar met het token Direct Line 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. Zodra u bent begonnen, kunt u elk gesprek identificeren en er verbinding mee maken 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 het antwoord van de agent op met behulp van hetzelfde token en conversationId. De opgehaalde Direct Line-responsactiviteiten bevatten de berichten van de gebruiker en agent. U kunt responsactiviteiten filteren op de naam van uw agent om alleen het reactiebericht van de agent 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 Direct Line-token te vernieuwen als uw toepassing een langdurig gesprek met de agent heeft. Het token verloopt, maar kan worden vernieuwd voordat het verloopt. Zie Direct Line Authentication voor meer informatie.

In het volgende voorbeeld wordt het token vernieuwd voor een bestaand Copilot Studio-gesprek:

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

Na het starten van een gesprek met de agent, gebruikt de JSON-payload van het gesprek de standaard Direct Line-activiteit van Microsoft Bot Framework. Zie Bot Framework Direct Line API voor meer informatie.

Overdrachtsactiviteit afhandelen

Als uw toepassing moet worden overgedragen aan een live agent, moet u de overdrachtsactiviteit afhandelen. De overdrachtsactiviteit wordt verzonden wanneer het knooppunt Overdracht naar agent wordt bereikt. U kunt meer te weten komen over de payload van de overdrachtsactiviteit.

Een welkomstbericht activeren

Als u wilt dat uw agent automatisch het begroetingssysteemonderwerp verzendt wanneer een gebruiker een gesprek start, verzendt u een activiteit met Type=event en Name=startConversation.