Κατανόηση του Πρωτοκόλλου Δραστηριότητας

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

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

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

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

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

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

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

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

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

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

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

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Σημείωμα

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

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

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

Εισερχόμενη δραστηριότητα: Ο χρήστης στέλνει ένα μήνυμα ή πραγματοποιεί μια ενέργεια που δημιουργεί μια δραστηριότητα.
Ο κώδικάς σας λαμβάνει τη δραστηριότητα και ο παράγοντας την επεξεργάζεται χρησιμοποιώντας TurnContext.
Ο παράγοντας σας αποστέλλει μία ή περισσότερες δραστηριότητες.
Η διαδικασία τελειώνει και το 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: Η κατάσταση για τη διαδικασία

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

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

Περιλαμβάνονται τα εξής:

Μήνυμα
ConversationUpdate
Συμβάν
Κλήση
Πληκτρολόγηση

Μήνυμα

Ένας συνηθισμένος τύπος δραστηριότητας είναι το Μήνυμα τύπου 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);
});

ConversationUpdate

Ο τύπος ConversationUpdate του Activity ειδοποιεί τον παράγοντα σας όταν τα μέλη συμμετέχουν ή αποχωρούν από μια συνομιλία. Δεν υποστηρίζουν όλοι οι πελάτες αυτήν την ειδοποίηση, αλλά το υποστηρίζει το 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. Στη συνέχεια, διαχειριστείτε την επιθυμητή λογική με βάση:

Όνομα: Το όνομα ή το αναγνωριστικό του συμβάντος από τον πελάτη.
Value: Περιεχόμενο συμβάντος που είναι συνήθως ένα αντικείμενο 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 365 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, κ.λπ. Είναι επίσης σημαντικό να γνωρίζετε ότι αυτοί οι σύνδεσμοι έχουν συνήθως μικρή διάρκεια ζωής, επομένως μην υποθέτετε ότι θα παραμείνουν έγκυροι για πολύ. Αυτός ο περιορισμός καθιστά σημαντική τη χρήση του δικού σας αποθηκευτικού χώρου σε περίπτωση που χρειαστεί να ανατρέξετε στα περιεχόμενα αργότερα.

Παραπομπές

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

Ειδικές παρατηρήσεις για τα κανάλια

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

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

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

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

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

Microsoft Teams

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

Microsoft 365 Copilot

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

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

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

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

Κανάλια εκτός της Microsoft

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

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

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

Μάθετε για το AgentApplication

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Last updated on 2026-07-30