Publicera en agent för mobila eller anpassade appar

Du kan ansluta agent till en egen app så att appens användare kan interagera med agent direkt från appen.

I de flesta fall är din anpassade app en mobilapp som antingen är en webbaserad app eller en inbyggd app. Det kan också vara en adapter till andra tjänster som ditt företag behöver.

Det finns olika procedurer för att ansluta till din mobilapp, beroende på om din app är en webbaserad app eller en inbyggd app.

Det är relativt enkelt att ansluta agenten till en webbaserad app, eftersom det innebär att kopiera en kodavsnitt i din app. Både webbaserade appar och inhemska eller anpassade appar behöver emellertid fortfarande betydande utvecklarkompetens för att helt integrera agenten i din app. I den här artikeln beskrivs båda procedurerna.

Förutsättningar

• .NET Core SDK version 2.1.
• NuGet-paketet Microsoft.Bot.Connector.DirectLine.
• En agent som skapades i Copilot Studio som du vill ansluta till din app.

Ansluta agenten till en webbaserad app

1. I Copilot Studio, väljer Kanaler på navigeringsmenyn.

2. Välj panelen Mobilapp för att öppna konfigurationsfönstret.

3. Kopiera koden under avsnittet Webbaserade appar och ge den till dina apputvecklare för att lägga till den i den webbaserade appen.

   

Anslut agenten till en inhemsk eller anpassad app

Om du vill ansluta till Azure Bot Service kanaler kan du läsa Publicera en agent till Azure Bot Service kanaler.

Referenser

Anvisningarna i det här dokumentet hänvisar till följande källmaterial:

• Bot Framework Direct Line API
• Direct Line-autentisering
• Kontextuella variabler tillgängliga vid överlämning
• Microsoft Bot Framework-aktivitet

Hämta dina parametrar för Copilot Studio-agent

Om du vill ansluta till agenten som du skapade hämtar du agentens namn och tokenslutpunkt för att identifiera den.

1. I Copilot Studio går du till sidan Overview i din agent och kopierar agentens namn.

2. Välj Kanaler>Mobilapp.

3. På sidan Mobilapp bredvid Tokenslutpunkt väljer du Kopiera. Du behöver denna slutpunkt för steget Hämta Direct Line-token.

   

Hämta Direct Line-token

För att starta en konversation med din agent, behöver du ett Direct Line-token. Hämta den här token genom att skicka en GET-begäran till slutpunkten som visas på Copilot Studio skärmen. Använd den här token som rubrik för nästa anrop till direktrads-API:et.

Exempel:

GET <BOT TOKEN ENDPOINT>

Om begäran lyckas returnerar slutpunkten en Direct Line-token, utgångstid och ett conversationId för den begärda agenten.

Exempel:

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

Hämta kodexempel för Direct Line-token

I följande exempel får man en Direct Line-token för en 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; }
}

Svarsobjektet är detsamma som den GET begäran du såg tidigare.

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

Använd Direct Line för att kommunicera med agenten

När du har hämtat Direct Line token är du redo att ha en konversation med din Copilot Studio-agent med hjälp av Direct Line. Om du vill starta en konversation och skicka och ta emot meddelanden följer du anvisningarna i Bot Framework Direct Line API.

I följande exempel startar en konversation och skickar och tar emot meddelanden från en Copilot Studio-agent.

1. Initiera en DirectLineClient-instans med Direct Line-token och starta en konversation:

      // 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. När du har startat kan du identifiera och ansluta till varje konversation med hjälp av kombinationen av token och conversationtId. Skicka ett användarmeddelande till en befintlig konversation:

      // 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. Hämta agentens svar med samma token och conversationId. De hämtade Direct Line svarsaktiviteterna innehåller både användarens och agentens meddelanden. Du kan filtrera svarsaktiviteten efter din agents namn om du endast vill få agentmeddelandet.

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

Uppdatera Direct Line-token

Du kan behöva lägga till kod för att uppdatera Direct Line-token om programmet har en lång konversation med agenten. Token upphör att gälla men kan uppdateras innan den upphör att gälla. Mer information finns i Direct Line Authentication.

I följande exempel uppdateras token för en befintlig Copilot Studio-konversation:

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

Analysera konversationens nyttolast från agenten

Efter att du har startat en konversation med agenten, använder JSON-nyttolasten för konversationen standardaktiviteten för Microsoft Bot Framework Direct Line. Mer information finns i Bot Framework Direct Line API.

Hantera överlämnande av aktivitet

Om ditt program behöver övergå till en live-agentleverantör måste du hantera övergången. Överlämningsaktiviteten skickas när noden Överför till agent nås. Du kan lära dig mer om nyttolasten för överlämningsaktiviteten.

Utlösa ett välkomstmeddelande

Om du vill att din agent automatiskt ska skicka hälsningssystemets ämne när en användare startar en konversation skickar du en aktivitet med Type=event och Name=startConversation.