Προσθήκη copilot σε εφαρμογή για κινητές συσκευές ή σε προσαρμοσμένη εφαρμογή

Άρθρο
04/19/2024

Σημαντικό

Οι δυνατότητες του Power Virtual Agents αποτελούν τώρα μέρος του Microsoft Copilot Studio μετά από σημαντικές επενδύσεις σε παραγωγική τεχνητή νοημοσύνη και βελτιωμένες ενσωματώσεις στο Microsoft Copilot.

Ορισμένα άρθρα και στιγμιότυπα οθόνης ενδέχεται να αναφέρονται στο Power Virtual Agents ενώ ενημερώνουμε την τεκμηρίωση και το εκπαιδευτικό περιεχόμενο.

Μπορείτε να συνδέσετε το copilot σας σε μια προσαρμοσμένη εφαρμογή ώστε οι χρήστες της εφαρμογής να μπορούν να αλληλεπιδρούν με το copilot απευθείας από την εφαρμογή σας.

Στις περισσότερες περιπτώσεις, η προσαρμοσμένη εφαρμογή σας είναι μια εφαρμογή για κινητές συσκευές που είναι είτε μια εφαρμογή που βασίζεται στο Web είτε μια εγγενής εφαρμογή ή προσαρμογέας σε άλλες υπηρεσίες που απαιτεί η επιχείρησή σας.

Υπάρχουν διαφορετικές διαδικασίες για τη σύνδεση στην εφαρμογή για κινητές συσκευές, ανάλογα με το αν η εφαρμογή σας είναι εφαρμογή που βασίζεται στο Web ή εγγενής εφαρμογή.

Η σύνδεση του copilot σας σε μια εφαρμογή που βασίζεται στο Web είναι σχετικά απλή, καθώς αφορά την αντιγραφή ενός τμήματος κώδικα στην εφαρμογή σας. Ωστόσο, τόσο οι εφαρμογές που βασίζονται στο Web όσο και οι εγγενείς ή προσαρμοσμένες εφαρμογές απαιτούν σημαντική εξειδίκευση προγραμματιστή προκειμένου να ενσωματώσουν πλήρως το copilot στην εφαρμογή σας. Και οι δύο διαδικασίες περιγράφονται σε αυτό το άρθρο.

Προϋποθέσεις

.NET Core SDK έκδοση 2.1.
Πακέτο Nuget Microsoft.Bot.Connector.DirectLine.
Ένα copilot που δημιουργήθηκε στο Copilot Studio και το οποίο θέλετε να συνδέσετε στην εφαρμογή σας.

Συνδέστε το copilot σας σε μια εφαρμογή βάσει Web

Στο Copilot Studio, στο μενού πλοήγησης, στις Ρυθμίσεις επιλέξτε Κανάλια.
Επιλέξτε το πλακίδιο Εφαρμογή για κινητές συσκευές για να ανοίξετε το παράθυρο ρύθμισης παραμέτρων.
Αντιγράψτε τον κώδικα στην ενότητα Εφαρμογής που βασίζονται στο web και δώστε τον στους προγραμματιστές εφαρμογών σας ώστε να τον προσθέσουν στην εφαρμογή σας που βασίζεται στο Web.

Συνδέστε το copilot σας σε μια εγγενή ή προσαρμοσμένη εφαρμογή

Φιλοδώρημα

Αν και σε αυτήν την ενότητα περιγράφεται ο τρόπος σύνδεσης σε μια εφαρμογή για κινητές συσκευές, η ίδια διαδικασία θα μπορούσε να εφαρμοστεί σε προσαρμοσμένες ή εγγενείς εφαρμογές, όπως οι εφαρμογές IoT (Internet of things).

Αν ο στόχος σας είναι η σύνδεση στα κανάλια Azure Bot Service, εκτός από τις οδηγίες που παρατίθενται εδώ, οι προγραμματιστές σας μπορούν να μάθουν περισσότερα στη Σύνδεση του bot σας σε κανάλια Azure Bot Service.

Σημαντικό

Οι οδηγίες σε αυτήν την ενότητα απαιτούν ανάπτυξη λογισμικού από εσάς ή από τους προγραμματιστές σας. Απευθύνονται σε έμπειρους επαγγελματίες IT, όπως διαχειριστές IT ή προγραμματιστές που έχουν κατανοήσει πολύ καλά τα εργαλεία για προγραμματιστές, τα βοηθητικά προγράμματα και τα IDE.

Δείγματα κώδικα

Τα τμήματα κώδικα που χρησιμοποιούνται σε αυτό το έγγραφο προέρχονται από:

Δείγμα κώδικα σύνδεσης

Αναφορές

Οι οδηγίες σε αυτό το έγγραφο αναφέρουν το εξής υλικό προέλευσης:

Ανάκτηση των παραμέτρων copilot Copilot Studio

Για να συνδεθείτε στο copilot που δημιουργήσατε, πρέπει να ανακτήσετε το όνομα του copilot και το τελικό σημείο διακριτικού για προσδιορισμό του.

Αντιγράψτε το όνομα του copilot στο Copilot Studio.
Στο μενού πλοήγησης, στις Ρυθμίσεις επιλέξτε Κανάλια.
Επιλέξτε Εφαρμογή για κινητές συσκευές.
Δίπλα στο Τελικό σημείο διακριτικού, επιλέξτε Αντιγραφή. Χρειάζεστε αυτό το τελικό σημείο για το βήμα Λήψη διακριτικού Direct Line.

Λήψη διακριτικού Direct Line

Για να ξεκινήσετε μια συνομιλία με το copilot, θα πρέπει να έχετε ένα διακριτικό Direct Line. Αυτό το διακριτικό μπορεί να ληφθεί με την υποβολή ενός αιτήματος GET στο τελικό σημείο υποδεικνύεται στην οθόνη του Copilot Studio. Αυτό το διακριτικό πρέπει στη συνέχεια να χρησιμοποιηθεί ως κεφαλίδα για επόμενες κλήσεις στο API απευθείας γραμμής.

Παράδειγμα:

GET <BOT TOKEN ENDPOINT>

Σε περίπτωση που το αίτημα είναι επιτυχές, θα επιστραφεί ένα διακριτικό Direct Line, ώρα λήξης και conversationId για το ζητούμενο copilot. Παράδειγμα:

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

Παράδειγμα δείγματος κώδικα

Στο παρακάτω παράδειγμα, χρησιμοποιούνται δείγματα από το δείγμα κώδικα σύνδεσης για τη λήψη ενός διακριτικού Direct Line για ένα copilot Copilot Studio.

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

Το αντικείμενο απάντησης είναι ίδιο με το αίτημα GET που είχαμε προηγουμένως.

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

Χρήση του Direct Line για επικοινωνία με το copilot

Μετά την ανάκτηση του διακριτικού Direct Line, είστε έτοιμοι για μια συνομιλία με το copilot Copilot Studio με τον χρήστη του Direct Line. Για να ξεκινήσετε μια συνομιλία και να στείλετε και να λάβετε μηνύματα, ακολουθήστε τις οδηγίες στο Bot Framework Direct Line API.

Στο παρακάτω παράδειγμα, χρησιμοποιούνται δείγματα από το δείγμα κώδικα του Connector για την έναρξη μιας συνομιλίας και την αποστολή και λήψη μηνυμάτων από ένα copilot του Copilot Studio.

Προετοιμασία μιας παρουσίας DirectLineClient με διακριτικό Direct Line και έναρξη μιας συνομιλίας:

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

Μόλις ξεκινήσει, κάθε συνομιλία μπορεί να αναγνωριστεί και να συνδεθεί χρησιμοποιώντας τον συνδυασμό του token και του conversationtId. Αποστολή μηνύματος χρήστη σε μια υπάρχουσα συνομιλία:

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

Ανάκτηση της απόκρισης του copilot με χρήση του ίδιου token και του conversationId. Οι δραστηριότητες απόκρισης Direct Line που ανακτήθηκαν περιέχουν τόσο τα μηνύματα του χρήστη όσο και του copilot. Μπορείτε να φιλτράρετε τις δραστηριότητες απόκρισης με το όνομα του copilot σας, για να λάβετε μόνο το μήνυμα απόκρισης του copilot.

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

Ίσως χρειαστεί να προσθέσετε κώδικα για να ανανεώσετε το διακριτικό Direct Line, εάν η εφαρμογή σας έχει μια χρονοβόρα συνομιλία με το copilot. Το διακριτικό λήγει αλλά μπορεί να ανανεωθεί πριν λήξει. Μάθετε περισσότερα στον Έλεγχο ταυτότητας Direct Line.

Στο παρακάτω παράδειγμα χρησιμοποιούνται δείγματα από τον κώδικα δείγματος Connector για ανανέωση του διακριτικού για μια υφιστάμενη συνομιλία Copilot Studio:

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

Ανάλυση του ωφέλιμου φορτίου συνομιλίας από το copilot

Μετά την έναρξη μιας συνομιλίας με το copilot, το ωφέλιμο φορτίο JSON συνομιλίας χρησιμοποιεί την τυπική Microsoft Bot Framework Direct Line δραστηριότητα. Μπορείτε να μάθετε περισσότερα στο Bot Framework Direct Line API.

Χειρισμός δραστηριότητας παράδοσης

Εάν η εφαρμογή σας πρέπει να παραδοθεί σε έναν εκπρόσωπο ζωντανής υποστήριξης, πρέπει να διαχειριστείτε τη δραστηριότητα παράδοσης. Η δραστηριότητα παράδοσης αποστέλλεται όταν κάντε κλικ στον κόμβο "Σύνδεση με εκπρόσωπο". Μπορείτε να μάθετε περισσότερα για το ωφέλιμο φορτίο της δραστηριότητας παράδοσης.

Ενεργοποίηση μηνύματος καλωσορίσματος

Εάν θέλετε το copilot σας να αυτόματα το θέμα συστήματος χαιρετισμού όταν ένας χρήστης ξεκινά μια συνομιλία, μπορείτε να στείλετε μια δραστηριότητα με τα Type=event και Name=startConversation.

Κοινή χρήση μέσω