Κατανόηση του πρωτοκόλλου δραστηριότητας

Το Activity Protocol είναι ένα πρωτόκολλο επικοινωνίας standard που χρησιμοποιείται σε Microsoft σε πολλά Microsoft SDK, υπηρεσίες και προγράμματα-πελάτες. Το πρωτόκολλο δραστηριότητας χρησιμοποιείται από το Microsoft Copilot, το Microsoft Copilot Studio, το Microsoft Teams και το SDK παραγόντων Microsoft 365. Το Πρωτόκολλο δραστηριότητας ορίζει τη δομή ενός Activity και τον τρόπο με τον οποίο τα μηνύματα, τα συμβάντα και οι αλληλεπιδράσεις ρέουν από ένα κανάλι στον κωδικά σας και οπουδήποτε αλλού στο ενδιάμεσο. Οι αντιπρόσωποι μπορούν να συνδεθούν σε ένα ή περισσότερα κανάλια για να αλληλεπιδράσουν με χρήστες και να εργαστούν με άλλους υπαλλήλους. Το Πρωτόκολλο δραστηριότητας τυποποιεί το πρωτόκολλο επικοινωνίας με οποιοδήποτε πρόγραμμα-πελάτη με το οποίο εργάζεστε, συμπεριλαμβανομένων προγραμμάτων-πελατών Microsoft και μη Microsoft, ώστε να μην χρειάζεται να δημιουργήσετε προσαρμοσμένη λογική για κάθε κανάλι.

Τι είναι μια δραστηριότητα;

Το A Activity είναι ένα δομημένο αντικείμενο JSON που αντιπροσωπεύει οποιαδήποτε αλληλεπίδραση μεταξύ ενός χρήστη και του παράγοντα σας. Οι δραστηριότητες δεν περιορίζονται σε μηνύματα που βασίζονται σε κείμενο. Μπορεί να περιλαμβάνει διάφορους τύπους αλληλεπίδρασης, όπως συμβάντα όπως η συμμετοχή ή η αποχώρηση ενός χρήστη για προγράμματα-πελάτες που υποστηρίζουν πολλούς χρήστες, ενδείξεις πληκτρολόγησης, αποστολές αρχείων, ενέργειες καρτών και προσαρμοσμένα συμβάντα που σχεδιάζουν οι προγραμματιστές.

Κάθε δραστηριότητα περιλαμβάνει μετα-δεδομένα σχετικά με:

• Ποιος την έστειλε (από)
• Ποιος πρέπει να τη λάβει (παραλήπτης)
• Το περιβάλλον συζήτησης
• Το κανάλι από το οποίο προήλθε
• Ο τύπος αλληλεπίδρασης
• Τα δεδομένα ωφέλιμου φορτίου

Σχήμα δραστηριότητας - βασικές ιδιότητες

Αυτή η προδιαγραφή ορίζει το Πρωτόκολλο δραστηριότητας: Πρωτόκολλο δραστηριότητας - Δραστηριότητα. Ορισμένες από τις βασικές ιδιότητες που ορίζονται στο Πρωτόκολλο δραστηριότητας είναι οι εξής:

Property	Περιγραφή
Id	Συνήθως δημιουργείται από το κανάλι, εφόσον προέρχεται από ένα κανάλι
Type	Ο τύπος ελέγχει την έννοια μιας δραστηριότητας, για παράδειγμα, τύπος μηνύματος
ChannelID	Το ChannelID αναφέρει το κανάλι από το οποίο προέρχεται η δραστηριότητα. Για παράδειγμα: msteams.
From	Ο αποστολέας της δραστηριότητας (ο οποίος μπορεί να είναι χρήστης ή εκπρόσωπος)
Recipient	Ο επιδιωκόμενος παραλήπτης της δραστηριότητας
Text	Το περιεχόμενο κειμένου του μηνύματος
Attachment	Εμπλουτισμένο περιεχόμενο, όπως κάρτες, εικόνες αρχείων

Πρόσβαση σε δεδομένα δραστηριότητας

Για να ολοκληρώσουν ενέργειες από το TurnContext αντικείμενο, οι προγραμματιστές πρέπει να έχουν πρόσβαση στα δεδομένα εντός της δραστηριότητας.

Μπορείτε να βρείτε μια TurnContext κλάση σε κάθε έκδοση γλώσσας του SDK Microsoft 365 Agents:

• .NET: TurnContext
• Python: TurnContext
• JavaScript: TurnContext

Σημείωμα

Τα τμήματα κώδικα σε αυτό το άρθρο χρησιμοποιούν C#. Η δομή σύνταξης και API για τις εκδόσεις JavaScript και Python είναι παρόμοια.

Το TurnContext είναι ένα σημαντικό αντικείμενο που χρησιμοποιείται σε κάθε στροφή συνομιλίας στην SDK παραγόντων Microsoft 365. Παρέχει πρόσβαση στην εισερχόμενη δραστηριότητα, τις μεθόδους για την αποστολή απαντήσεων, τη διαχείριση της κατάστασης συνομιλίας και το περιβάλλον που απαιτείται για τον χειρισμό μιας μοναδικής στροφής της συνομιλίας. Χρησιμοποιήστε το για να διατηρήσετε το περιβάλλον, να στείλετε κατάλληλες απαντήσεις και να αλληλεπιδράσετε αποτελεσματικά με τους χρήστες στο πρόγραμμα-πελάτη ή το κανάλι τους. Κάθε φορά που ο πράκτοράς σας λαμβάνει μια νέα δραστηριότητα από ένα κανάλι, το SDK Αντιπροσώπων δημιουργεί μια νέα TurnContext παρουσία και τη μεταβιβάζει στους εγγεγραμμένους χειρισμούς ή μεθόδους σας. Αυτό το αντικείμενο περιβάλλοντος υπάρχει κατά τη διάρκεια της μοναδικής στροφής και, στη συνέχεια, απορρίπτεται μόλις λήξει η στροφή.

Μια επανάληψη ορίζεται ως ο κύκλος ενός μηνύματος που αποστέλλεται από τον πελάτη και κάνει τη διαδρομή προς τον κώδικά σας. Ο κώδικάς σας χειρίζεται αυτά τα δεδομένα και μπορεί προαιρετικά να στείλει μια απόκριση για να ολοκληρώσει τη στροφή. Αυτή η διαδρομή μετ 'επιστροφής μπορεί να χωριστεί στα ακόλουθα βήματα:

1. Εισερχόμενη δραστηριότητα: Ο χρήστης στέλνει ένα μήνυμα ή εκτελεί μια ενέργεια που δημιουργεί μια δραστηριότητα.

2. Ο κώδικάς σας λαμβάνει τη δραστηριότητα και ο παράγοντας την επεξεργάζεται χρησιμοποιώντας το TurnContext.

3. Ο ατζέντης σας αποστέλλει μία ή περισσότερες δραστηριότητες πίσω.

4. Η στροφή τελειώνει και η TurnContext απορρίπτεται.

Αποκτήστε πρόσβαση σε δεδομένα από το TurnContext, όπως:

var messageText = turnContext.Activity.Text;
var channelID = turnContext.Activity.ChannelId;

Αυτό το τμήμα κώδικα εμφανίζει ένα παράδειγμα πλήρους στροφής:

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text;
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

Μέσα στην TurnContext κλάση, οι συνήθεις βασικές πληροφορίες περιλαμβάνουν τα εξής:

• Δραστηριότητα: Ο κύριος τρόπος λήψης πληροφοριών από τη δραστηριότητα
• Προσαρμογέας: Ο προσαρμογέας καναλιού που δημιούργησε τη δραστηριότητα
• TurnState: Η κατάσταση για τη στροφή

Τύποι δραστηριότητας

Ο τύπος μιας δραστηριότητας ορίζει τι απαιτεί ή αναμένει η υπόλοιπη δραστηριότητα μεταξύ πελατών, χρηστών και αντιπροσώπων.

Σε αυτούς περιλαμβάνονται τα εξής:

• Μήνυμα
• Ενημέρωση συνομιλίας
• Συμβάν
• Επικαλούμαι
• Πληκτρολόγηση

Μήνυμα

Ένας συνηθισμένος τύπος δραστηριότητας είναι ο τύπος μηνύματος .Activity Αυτός Activity ο τύπος μπορεί να περιλαμβάνει κείμενο, συνημμένα και προτεινόμενες ενέργειες.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text;
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

Ενημέρωση συνομιλίας

Ο τύπος Ενημέρωση ΣυνομιλίαςActivity ειδοποιεί το bot σας όταν τα μέλη συμμετέχουν ή αποχωρούν από μια συνομιλία. Δεν υποστηρίζουν όλα τα προγράμματα-πελάτες αυτή την ειδοποίηση, αλλά Microsoft Teams το κάνουν.

Το ακόλουθο τμήμα κώδικα χαιρετά τα νέα μέλη σε μια συνομιλία:

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Εκδηλώσεις

Ο τύπος συμβάντοςActivity είναι ένα προσαρμοσμένο συμβάν που χρησιμοποιούν τα κανάλια ή τα προγράμματα-πελάτες για την αποστολή δομημένων δεδομένων στον πράκτορά σας. Αυτά τα δεδομένα δεν είναι προκαθορισμένα στη Activity δομή ωφέλιμου φορτίου.

Πρέπει να δημιουργήσετε μια μέθοδο ή χειρισμό δρομολόγησης για τον συγκεκριμένο Event τύπο. Στη συνέχεια, διαχειριστείτε την επιθυμητή λογική με βάση τα εξής:

• Όνομα: Το όνομα ή το αναγνωριστικό του συμβάντος από το πρόγραμμα-πελάτη
• Τιμή: Ωφέλιμο φορτίο συμβάντος που είναι συνήθως αντικείμενο JSON

agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>
{
    var eventName = turnContext.Activity.Name;
    var eventValue = turnContext.Activity.Value;

    // custom event (E.g. a switch on eventName)
});

Επικαλούμαι

Ένας τύπος κλήσης είναι ένας συγκεκριμένος Activity τύπος δραστηριότητας που καλεί ένα πρόγραμμα-πελάτη σε έναν παράγοντα για την εκτέλεση μιας εντολής ή λειτουργίας. Δεν είναι απλά ένα μήνυμα. Παραδείγματα αυτών των τύπων δραστηριοτήτων είναι κοινά στο Microsoft Teams για task/fetch και task/submit. Δεν υποστηρίζουν όλα τα κανάλια αυτούς τους τύπους δραστηριοτήτων.

Πληκτρολόγηση

Ένας τύπος πληκτρολόγησηςActivity είναι μια ταξινόμηση της δραστηριότητας που υποδεικνύει ότι κάποιος πληκτρολογεί σε μια συνομιλία. Αυτή η δραστηριότητα παρατηρείται συνήθως μεταξύ συνομιλιών από άνθρωπο σε άνθρωπο σε Microsoft Teams πελάτη, για παράδειγμα. Οι δραστηριότητες πληκτρολόγησης δεν υποστηρίζονται σε κάθε πρόγραμμα-πελάτη. Συγκεκριμένα, το Microsoft Copilot δεν υποστηρίζει δραστηριότητες πληκτρολόγησης.

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken);

Δημιουργία και αποστολή δραστηριοτήτων

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

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken); // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken); // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken); // send multiple activities in an Activity array
}

Εργασία με συνημμένα

Οι αντιπρόσωποι συχνά εργάζονται με συνημμένα που υποβάλλουν οι χρήστες (ή ακόμα και άλλοι αντιπρόσωποι). Το πρόγραμμα-πελάτης στέλνει μια Message δραστηριότητα που περιλαμβάνει ένα συνημμένο (δεν είναι ένας συγκεκριμένος τύπος δραστηριότητας). Ο κώδικάς σας πρέπει να χειριστεί τη λήψη του μηνύματος με το συνημμένο, να διαβάσει τα μετα-δεδομένα και να λάβει με ασφάλεια το αρχείο από τη διεύθυνση URL που παρείχε το πρόγραμμα-πελάτης. Συνήθως, μετακινείτε το αρχείο στον χώρο αποθήκευσής σας.

Για να λάβετε ένα συνημμένο

Ο παρακάτω κώδικας δείχνει πώς μπορείτε να λάβετε ένα συνημμένο.

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count > 0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        };
    }
}

Συνήθως, για να λάβει το έγγραφο για το συνημμένο, το πρόγραμμα-πελάτης αποστέλλει μια αίτηση ελέγχου GET ταυτότητας για την ανάκτηση των πραγματικών περιεχομένων. Κάθε προσαρμογέας έχει τον δικό του τρόπο για τη λήψη αυτών των δεδομένων. Για παράδειγμα, το Teams, OneDrive και ούτω καθεξής. Είναι επίσης σημαντικό να γνωρίζετε ότι αυτές οι διευθύνσεις URL είναι συνήθως βραχύβιες και, επομένως, μην υποθέσετε ότι οι διευθύνσεις URL παραμένουν σε ισχύ για μεγάλο χρονικό διάστημα. Αυτός είναι ο λόγος για τον οποίο η μετακίνηση στον δικό σας χώρο αποθήκευσης είναι σημαντικός εάν θέλετε να ανατρέξετε στα περιεχόμενα αργότερα.

Παραπομπές

Είναι σημαντικό να γνωρίζετε ότι οι συναρτήσεις Attachment και Citation δεν έχουν τον ίδιο τύπο αντικειμένου. Τα προγράμματα-πελάτες, όπως Microsoft Teams, χειρίζονται αναφορές με τον δικό τους τρόπο. Χρησιμοποιούν την ιδιότητα Οντότητες του Activity. Μπορείτε να προσθέσετε αναφορές με activity.Entities.Add και να προσθέσετε ένα νέο Entity αντικείμενο που έχει τον συγκεκριμένο Citation ορισμό με βάση το πρόγραμμα-πελάτη σας. Σειριοποιείται ως αντικείμενο JSON, το οποίο το πρόγραμμα-πελάτης αποειδικοποιεί με βάση τον τρόπο που αποδίδεται στο πρόγραμμα-πελάτη. Βασικά, τα Συνημμένα είναι μηνύματα και οι αναφορές μπορεί να αναφέρουν συνημμένα και είναι ένα άλλο αντικείμενο που αποστέλλεται στο EntitiesActivity ωφέλιμο φορτίο.

Ζητήματα για συγκεκριμένα κανάλια

Το SDK παραγόντων Microsoft 365 έχει δημιουργηθεί ως "Διανομέας" που χρησιμοποιούν οι προγραμματιστές για τη δημιουργία αντιπροσώπων που μπορούν να εργαστούν με any πρόγραμμα-πελάτη, συμπεριλαμβανομένων των προγραμμάτων-πελατών που υποστηρίζουμε. Παρέχει τα εργαλεία που παρέχουν στους προγραμματιστές για να δημιουργήσουν τον δικό τους προσαρμογέα καναλιού χρησιμοποιώντας το ίδιο πλαίσιο. Αυτή η αρχιτεκτονική παρέχει στους προγραμματιστές το μεγαλύτερο δυνατό εύρος όσον αφορά τους υπαλλήλους και παρέχει επεκτασιμότητα στους υπολογιστές-πελάτες για σύνδεση σε αυτόν τον κόμβο, που μπορεί να είναι ένα ή περισσότερα προγράμματα-πελάτες, όπως Microsoft Teams, Slack και πολλά άλλα.

Διαφορετικά κανάλια έχουν διαφορετικές δυνατότητες και περιορισμούς.

Μπορείτε να ελέγξετε το κανάλι από το οποίο λάβατε τη δραστηριότητα ελέγχοντας την channelId ιδιότητα στο Activity.

Τα κανάλια περιλαμβάνουν συγκεκριμένα δεδομένα που δεν συμμορφώνονται με το γενικό Activity ωφέλιμο φορτίο σε όλα τα κανάλια. Μπορείτε να αποκτήσετε πρόσβαση σε αυτά τα δεδομένα από την ιδιότητα, ρίχνοντάς τα TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) σε μεταβλητές για χρήση στον κώδικά σας.

Οι παρακάτω ενότητες συνοψίζουν ζητήματα όταν εργάζεστε με συνήθη προγράμματα-πελάτες.

Ομάδες της Microsoft

• Υποστηρίζει πλούσια Προσαρμόσιμες κάρτες με προηγμένες δυνατότητες.
• Υποστηρίζει ενημερώσεις και διαγραφές μηνυμάτων.
• Διαθέτει συγκεκριμένα δεδομένα καναλιού για δυνατότητες του Teams, όπως αναφορές και πληροφορίες σύσκεψης.
• Υποστηρίζει την ενεργοποίηση ενεργειών για λειτουργικές μονάδες εργασιών.

Microsoft Copilot

• Κυρίως στις δραστηριότητες μηνυμάτων.
• Υποστηρίζει παραπομπές και αναφορές στις απαντήσεις.
• Απαιτεί αποκρίσεις ροής.
• Περιορισμένη υποστήριξη για εμπλουτισμένες κάρτες και προσαρμόσιμες κάρτες.

Συνομιλία στο Web/DirectLine

Συνομιλία στο Web είναι ένα πρωτόκολλο HTTP που μπορούν να χρησιμοποιήσουν οι πράκτορες για να επικοινωνήσουν μέσω HTTPS.

• Πλήρης υποστήριξη για όλους τους τύπους δραστηριότητας.
• Υποστηρίζει δεδομένα προσαρμοσμένου καναλιού.

Κανάλια που δεν είναι Microsoft

Αυτά τα κανάλια περιλαμβάνουν τα Slack, Facebook και πολλά άλλα.

• Μπορεί να έχει περιορισμένη υποστήριξη για συγκεκριμένους τύπους δραστηριότητας.
• Η απόδοση της κάρτας μπορεί να είναι διαφορετική ή μη υποστηριζόμενη.
• Να ελέγχετε πάντα την τεκμηρίωση συγκεκριμένου καναλιού.

Επόμενα βήματα

• Μάθετε σχετικά με το AgentApplication