Lägg till copilot i mobila och anpassade appar

Viktigt

Power Virtual Agents-funktioner ingår nu i Microsoft Copilot Studio efter betydande investeringar i generativ AI och förbättrade integrationer mellan Microsoft Copilot.

Vissa artiklar och skärmbilder kan referera till Power Virtual Agents när vi uppdaterar dokumentation och utbildning.

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

I de flesta fall är din anpassade app en mobilapp som antingen är en webbaserad app eller en inbyggd app eller adapter till andra tjänster som ditt företag kräver.

Det finns olika sätt att ansluta till din mobilapp, beroende på om din app är en webbaserad app eller en ursprunglig app.

Det är relativt enkelt att ansluta copilot till en webbaserad app, eftersom det innebär att kopiera en kodavsnitt i din app. Både webbaserade appar och egna eller anpassade appar behöver emellertid fortfarande stora kunskaper i utvecklingsarbetet för att kunna integrera copilot i din app. Båda procedurerna beskrivs i den här artikeln.

Förutsättningar

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

Ansluta copilot till en webbaserad app

1. I Copilot Studio, i navigeringsmenyn under Inställningar, väljer du Kanaler.

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

3. Kopiera koden under avsnittet Webbaserade appar och lämna apputvecklare som ska läggas till i den webbaserade appen.

   

Anslut copilot till en egen eller egen app

Dricks

I det här avsnittet beskrivs hur du ansluter till en mobilapp, men samma process kan användas för anpassade appar, t.ex. IoT (sakernas Internet).

Om målet är att ansluta till Azure Bot Service-kanalerna, utöver anvisningarna i det här avsnittet, kan dina utvecklare få mer information om hur du ansluter robot till Azure Bot Service-kanaler.

Viktigt!

Instruktioner i det här avsnittet kräver programvaruutveckling från dig eller dina utvecklare. Den är avsedd för erfarna IT-proffs, t.ex. IT-administratörer eller IT-utvecklare med en gedigen förståelse för utvecklarverktyg, verktyg samt IDE:er.

Kodexempel

Kodavsnitt som används i det här dokumentet är från:

• Anslutningsprogram exempelkod

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 Copilot Studio copilot-parametrar

Om du vill ansluta till den copilot som du har skapat måste du hämta din copilot namn och tokenslutpunkt för att identifiera den.

1. Kopiera namnet på copilot till Copilot Studio.

   

2. I navigeringsmenyn, under Inställningar, väljer du Kanaler.

3. Välj Mobilapp.

   

4. Bredvid tokenslutpunkt, välj 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 copilot behöver du ett Direct Line-token. Denna token kan hämtas genom att göra en GET-förfrågan till slutpunkt som visas på Copilot Studio-skärmen. Denna token måste sedan användas som rubrik för efterföljande anrop till Directline API.

Exempel:

GET <BOT TOKEN ENDPOINT>

Om förfrågan lyckas returneras Direct Line token, utgångstid och ett conversationId för den begärda copilot. Exempel:

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

Exempel på exempelkod

I följande exempel används exempel från exempelkoden för anslutningsprogram för att hämta Direct Line-token för en 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; }
}

Svarsobjektet är samma som i GET-förfrågan som vi såg tidigare.

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

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

När du har hämtat ett Direct Line-token är du redo för en konversation med din Copilot Studio copilot med Direct Line. För att starta en konversation och skicka och ta emot meddelanden, följ instruktionerna på Bot Framework Direct Line API.

I följande exempel används exempel från Anslutningsprogram exempelkod för att starta en konversation och skicka och ta emot meddelanden från en Copilot Studio-copilot.

1. Initiera en DirectLineClient-instans med din 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 en konversation har startats kan den identifieras och kopplas ihop med hjälp av kombinationen 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 copilot-svar med samma token och conversationId. De hämtade Direct Line-svarsaktiviteterna innehåller både användarens och copilot-meddelanden. Du kan filtrera svarsaktiviteten efter copilot-namn om du endast vill få copilot-meddelandet.

      // 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 copilot. Token förfaller men kan uppdateras innan det upphör att gälla. Läs mer på Direct Line-autentisering.

I följande exempel används exempel från Anslutningsprogram exempelkod för att uppdatera 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 copilot

När du har startat en konversation med copilot använder konversationens JSON-nyttolast Microsoft Bot Framework Direct Line-standardaktivitet. Du kan läsa mer på Bot Framework Direct Line API.

Hantera överlämnande av aktivitet

Om ditt program behöver överlämnas till en live-handläggare måste du överlämna aktiviteten. Överlämningsaktiviteten skickas när noden "Överför till handläggare" trycks ned. Du kan läsa mer om nyttolast för av överlämningsaktiviteten.

Utlösa ett välkomstmeddelande

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