Δημοσίευση παράγοντα στα κανάλια Azure Bot Service

Άρθρο
12/31/2024

Μπορείτε να συνδέσετε τον παράγοντά σας με υπάρχοντα κανάλια Azure Bot Service τα οποία μπορεί να είναι χρήσιμα εάν θέλετε να συνδέσετε τον παράγοντά σας με πελάτες στα κανάλια Azure Bot Service.

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

Φιλοδώρημα

Δεν χρειάζεται να ακολουθήσετε αυτό το έγγραφο για να προσθέσετε τον παράγοντα Copilot Studio στην τοποθεσία Web σας, στο Facebook ή στο Microsoft Teams. Αν ο στόχος σας είναι η σύνδεση σε μια προσαρμοσμένη εφαρμογή που βασίζεται στο Web ή σε μια εγγενή εφαρμογή, οι προγραμματιστές σας μπορούν να μάθουν περισσότερα από την επιλογή Δημοσίευση παράγοντα σε εφαρμογές για κινητές εφαρμογές ή προσαρμοσμένες εφαρμογές.

Σημαντικό

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

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

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

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

Τα τμήματα κώδικα που χρησιμοποιούνται σε αυτό το έγγραφο προέρχονται από το δείγμα κώδικα bot αναμετάδοσης.

Αναφορές

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

Αναπτύξτε το δικό σας bot στο Azure για οδηγίες σχετικά με την ανάπτυξη του Azure Bot Service bot.
Κανάλια Azure Bot Service για σύνδεση σε οποιοδήποτε κανάλι που υποστηρίζεται από το Azure Bot Service.
Εντοπισμός σφαλμάτων του Azure Bot Service με το πρόγραμμα προσομοίωσης για οδηγίες σχετικά με τον εντοπισμό σφαλμάτων του Azure Bot Service bot.

Δημιουργία ή χρήση υφιστάμενου Azure Bot Service bot

Χρειάζεστε ένα Azure Bot Service bot που μπορεί να αναμεταδίδει συνομιλίες μεταξύ του παράγοντα Copilot Studio και των καναλιών Azure Bot Service.

Διάγραμμα bot αναμετάδοσης.

Το δείγμα κώδικα bot αναμετάδοσης είναι ένα καλό σημείο εκκίνησης εάν δεν έχετε κάποιο υφιστάμενο Azure Bot Service bot. Έχει δημιουργηθεί από δείγμα κώδικα του Microsoft Bot Framework bot που μπορεί να δημιουργηθεί και να αναπτυχθεί στο Azure Bot Service. Το δείγμα κώδικα προορίζεται για χρήση ως σημείο εκκίνησης και δεν προορίζεται για άμεση χρήση στην παραγωγή. Θα χρειαστεί να προσθέσετε κώδικα και βελτιστοποίηση ώστε να ικανοποιούνται οι ανάγκες της επιχείρησής σας.

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

Λήψη παραμέτρων παράγοντα Copilot Studio

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

Αντιγράψτε το όνομα του παράγοντα στο Copilot Studio.
Στο μενού πλοήγησης, στις Ρυθμίσεις επιλέξτε Κανάλια.
Επιλέξτε το κανάλι στο οποίο θέλετε να συνδεθείτε. Αυτό το σενάριο χρησιμοποιεί το Slack ως παράδειγμα.
Για να αντιγράψετε και να αποθηκεύσετε την τιμή Τελικό σημείο διακριτικού, επιλέξτε Αντιγραφή. Θα χρειαστείτε το τελικό σημείο για να συνδέσετε το παράγοντα με το κανάλι Azure Bot Service.

Διαχείριση περιόδων λειτουργίας συνομιλίας με το δικό σας παράγοντα Copilot Studio

Μπορεί να υπάρχουν πολλαπλές συνομιλίες μεταξύ των καναλιών Azure Bot Service και της σύνδεσης Direct Line με το παράγοντα Copilot Studio.

Το Azure Bot Service bot πρέπει να αντιστοιχίσει και να αναδιανείμει τη συνομιλία από το κανάλι Azure Bot Service στη συνομιλία Direct Line με το παράγοντα Copilot Studio και αντιστρόφως.

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

Στο παρακάτω παράδειγμα χρησιμοποιούνται δείγματα από το δείγμα κώδικα bot αναμετάδοσης.

Σε κάθε νέα εξωτερική συνομιλία καναλιού Azure Bot Service, ξεκινήστε μια συνομιλία παράγοντα Copilot Studio. Ανατρέξτε στη Λήψη διακριτικού Direct Line και στη Χρήση Direct Line για να επικοινωνήσετε με τον παράγοντα για οδηγίες σχετικά με την έναρξη μιας νέας συνομιλίας με το bot.

using (var httpRequest = new HttpRequestMessage())
{   
    httpRequest.Method = HttpMethod.Get;
    UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
    httpRequest.RequestUri = uriBuilder.Uri;
    using (var response = await s_httpClient.SendAsync(httpRequest))
    {
        var responseString = await response.Content.ReadAsStringAsync();
        string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
    }
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
    public string Token { get; set; }
}

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

Για να διαχειριστείτε πολλαπλές περιόδους λειτουργίας, θα πρέπει να διατηρήσετε μια αντιστοίχιση των εξωτερικών συνομιλιών καναλιού Azure Bot Service σε αντίστοιχες συνομιλίες παράγοντα Copilot Studio. Μια συνομιλία παράγοντα Copilot Studio μπορεί να προσδιοριστεί και να συνδεθεί με δύο ιδιότητες: ConversationtId και Token.
```
Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();  
```
Για να διαχειριστείτε τον κύκλο ζωής συνομιλιών, ανανεώστε τα Direct Line διακριτικά ή εκκαθαρίστε τις συνομιλίες που έχουν παραμείνει σε αδράνεια. Μάθετε περισσότερα σχετικά με την ανανέωση διακριτικού στην Ανανέωση διακριτικού Direct Line. Μια συνομιλία παράγοντα του Copilot Studio για υποστήριξη της ανανέωσης διακριτικών Direct Line ορίζεται ως εξής:
```
/// <summary>
/// Data model class for Copilot Studio agent conversation
/// </summary>
public class PowerVirtualAgentsConversation
{
    public string ConversationtId { get; set; } // The Copilot Studio agent conversation ID retrieved from step 1

    public string Token { get; set; } // The DirectLine token retrieved from step 1

    public string WaterMark { get; set; } // Identify turn in a conversation

    public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh

    public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to agent
}
```

Όταν ξεκινήσει μια νέα συνομιλία παράγοντα Copilot Studio, προσθέστε ένα ζεύγος κλειδιών-τιμής (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) στον πίνακα αντιστοίχισης.

// After new Copilot Studio agent conversation starts
ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
  {
    Token = token,
    ConversationtId = conversationId,
    WaterMark = null,
    LastConversationUpdateTime = DateTime.Now,
    LastTokenRefreshTime = DateTime.Now,
  };

Για να συνεχίσετε σε μια υπάρχουσα συνομιλία, μόλις ληφθεί ένα νέο μήνυμα εξωτερικού καναλιού Azure Bot Service, ανακτήστε την υπάρχουσα συνομιλία από τον πίνακα αντιστοίχισης, αναμεταδώστε την εξωτερική δραστηριότητα συνομιλίας στο παράγοντα Copilot Studio σας και λάβετε μια απόκριση.

Το παρακάτω δείγμα δείχνει τη συνομιλία αναμετάδοσης παρακάμπτοντας τη μέθοδο ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken)

// Invoked when a message activity is received from the user
// Send the user message to Copilot Studio agent and get response
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Retrieve agent conversation from mapping table
    // If not exists for the given external conversation ID, start a new Copilot Studio agent conversation
    ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
            currentConversation : /*await StartBotConversationAsync(externalCID)*/;

    // Create DirectLine client with the token associated to current conversation
    DirectLineClient client = new DirectLineClient(currentConversation.Token);

    // Send user message using directlineClient
    await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
    {
      Type = DirectLineActivityTypes.Message,
      From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
      Text = turnContext.Activity.Text,
      TextFormat = turnContext.Activity.TextFormat,
      Locale = turnContext.Activity.Locale,
    });

    // Update LastConversationUpdateTime for session management
    currentConversation.LastConversationUpdateTime = DateTime.Now;
}

Ανατρέξτε στη Χρήση Direct Line για επικοινωνία με τον παράγοντα για το πώς να λάβετε την απόκριση του παράγοντα Copilot Studio. Όταν ληφθεί η απάντηση του παράγοντα Copilot Studio, δείτε την Ανάλυση ωφέλιμου φορτίου συνομιλιας από τον παράγοντα για τον τρόπο ανάλυσης της απόκρισης στην απόκριση εξωτερικού καναλιού Azure Bot Service.

Παράδειγμα ανάλυσης απόκρισης υπάρχει στο δείγμα κώδικα bot αναμετάδοσης ResponseConverter.cs.

Ανάπτυξη στο Azure Bot Service

Αφού έχετε έτοιμο το bot αναμετάδοσης Azure Bot Service, θα πρέπει να αναπτύξετε το bot στο Azure Bot Service.

Ρύθμιση παραμέτρων καναλιών Azure Bot Service

Μπορείτε να ρυθμίσετε τα κανάλια στα οποία θέλετε να συνδεθείτε, κατόπιν σύνδεσής σας στην πύλη Azure και επιλέγοντας την ομάδα πόρων Azure Bot Service που έχετε αναπτύξει. Δείτε τις συγκεκριμένες οδηγίες για κάθε κανάλι στα Κανάλια Azure Bot Service.

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