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

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

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

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

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

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

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

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

Ιδιότητα	Περιγραφή
`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 παρουσία και τη διαβιβάζει στους εγγεγραμμένους χειρισμούς/μεθόδους σας. Αυτό το αντικείμενο περιβάλλοντος υπάρχει κατά τη διάρκεια της μοναδικής στροφής και, στη συνέχεια, απορρίπτεται όταν λήξει η στροφή.

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

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

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

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

Μήνυμα

Ένας συνηθισμένος τύπος δραστηριότητας είναι ο τύπος Μηνύματος , 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.Reciepient.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 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 και ούτω καθεξής. Είναι επίσης σημαντικό να γνωρίζετε ότι αυτές οι διευθύνσεις URL είναι συνήθως βραχύβιες και επομένως μην υποθέσετε ότι θα παραμείνουν εκεί. Αυτός είναι ο λόγος για τον οποίο η μετακίνηση στον δικό σας χώρο αποθήκευσης είναι σημαντική εάν πρέπει να αναφερθείτε σε αυτό αργότερα.

Αναφορές

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

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

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

Τα διαφορετικά κανάλια έχουν διαφορετικές δυνατότητες και περιορισμούς και τα παρακάτω είναι μια σύνοψη των ζητημάτων που αφορούν την εργασία με συνήθη προγράμματα-πελάτες.

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

Τα κανάλια περιλαμβάνουν συγκεκριμένα δεδομένα που δεν συμμορφώνονται με το γενικό Activity ωφέλιμο φορτίο σε όλα τα κανάλια και είναι δυνατή η πρόσβαση σε αυτά από το TurnContext.Activity.ChannelData και συγκεκριμένα σε μεταβλητές για χρήση στον κείμενό σας.

Ομάδες της Microsoft

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

Microsoft 365 Copilot

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

WebChat/DirectLine

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

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

Κανάλια τρίτων

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

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

Ανάδραση

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

Last updated on 2025-10-21