הכרת פרוטוקול פעילות

Activity Protocol הוא פרוטוקול standard communication protocol המשמש ב- Microsoft ב- SDK, שירותים והלקוחות של Microsoft רבים. פרוטוקול פעילות משמש את Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams ואת Microsoft 365 Agents SDK. פרוטוקול פעילות מגדיר את המבנה של וכיצד Activity הודעות, אירועים ואינטראקציות זורמים מערוץ לקוד שלך ובכל מקום אחר באמצע. נציגים יכולים להתחבר לערוצים אחד או יותר כדי לקיים אינטראקציה עם משתמשים ולעבוד עם נציגים אחרים. פרוטוקול פעילות תקנים את פרוטוקול התקשורת עם כל לקוח שאתה עובד איתו, כולל לקוחות Microsoft ולקוחים שאינם של Microsoft, כדי שלא תצטרך ליצור לוגיקה מותאמת אישית עבור כל ערוץ.

מהי פעילות?

An Activity הוא אובייקט JSON מובנים המייצג כל אינטראקציה בין משתמש לסוכן שלך. פעילויות אינן מוגבלות להודעות מבוססות טקסט. הם יכולים לכלול סוגים שונים של אינטראקציה, כגון אירועים כגון הצטרפות או עזיבה של משתמש עבור לקוחות התומכים במשתמשים מרובים, מחווני הקלדה, העלאות קבצים, פעולות כרטיס ואירועים מותאמים אישית שמפתחים מעצבים.

כל פעילות כוללת מטה-נתונים אודות:

• מי שלח אותו (מתוך)
• מי צריך לקבל אותו (נמען)
• הקשר השיחה
• הערוץ שממנו הוא הגיע
• סוג האינטראקציה
• נתוני המטען

סכימת פעילות - מאפייני מפתח

מפרט זה מגדיר פרוטוקול פעילות: Activity Protocol - פעילות. להלן כמה ממאפיינים עיקריים המוגדרים בפרוטוקול פעילות:

מאפיין‬	תיאור
Id	בדרך כלל נוצר על-ידי הערוץ אם הוא מגיע מערוץ
Type	הסוג קובע את המשמעות של פעילות, לדוגמה, סוג הודעה
ChannelID	הערוץ ChannelID מפנה לערוץ שממנו נוצרה הפעילות. לדוגמה: msteams.
From	שולח הפעילות (שעשוי להיות משתמש או סוכן)
Recipient	הנמען המיועד של הפעילות
Text	תוכן הטקסט של ההודעה
Attachment	תוכן עשיר כגון כרטיסים, תמונות של קבצים

גישה לנתונים של פעילות

כדי להשלים פעולות מהאובייקט TurnContext , מפתחים צריכים לגשת לנתונים בתוך הפעילות.

באפשרותך למצוא מחלקת TurnContext בכל גירסת שפה של Microsoft 365 Agents SDK:

• .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);
});

עדכון שיחה

סוג 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 . לאחר מכן, נהל את הלוגיקה הרצויה בהתבסס על:

• שם: שם האירוע או המזהה מהלקוח
• ערך: תוכן מנה של אירוע שהוא בדרך כלל אובייקט 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)
});

להפעיל

סוג InvokeActivity הוא סוג ספציפי של פעילות שבה לקוח קורא לסוכן לבצע פקודה או פעולה. זו לא רק הודעה. דוגמאות לסוגי פעילויות אלה נפוצות ב- 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 אלה קצרות בדרך כלל, ולכן אל תניחו כי כתובות ה- URL נשארות חוקיות למשך זמן רב. מגבלה זו היא מדוע המעבר לאחסון שלך חשוב אם עליך לעיין בתוכן במועד מאוחר יותר.

אזכורים

חשוב לדעת שקובץ מצורףוציטוט אינם מסוג אובייקט זהה. לקוחות, כגון Microsoft Teams, מטפלים בציטוטים בדרכים שלהם. הם משתמשים במאפיין ישויות של Activity. באפשרותך להוסיף ציטוטים עם activity.Entities.Add ולהוסיף אובייקט חדש Entity בעל ההגדרה הספציפית Citation בהתבסס על הלקוח שלך. הוא עובר סריאליזציה כאובייקט JSON שהלקוח מבצע דה-סיריאליזציה בהתאם לאופן שבו הוא מוצג בלקוח. באופן יסודי, קבצים מצורפים הם הודעות, וציטוטים יכולים להפנות לקבצים מצורפים, שהם אובייקט אחר שנשלח Entities מתוך Activity תוכן המנה.

שיקולים ספציפיים לערוץ

ה- Microsoft 365 Agents SDK נבנה כ'מרכז' שבו מפתחים משתמשים כדי ליצור סוכנים שניתן לעבוד איתם עם כל לקוח, כולל הלקוחות שבהם אנו תומכים. הוא מספק למפתחים את הכלים לבניית מתאם ערוץ משלהם באמצעות אותה מסגרת. ארכיטקטורה זו מעניקה למפתחים רוחב בכל הנוגע לסוכנים ומספקת יכולת הרחבה ללקוחות להתחבר לרכזת זו, שיכולה לכלול לקוח אחד או יותר, כגון Microsoft Teams, Slack ועוד.

לערוצים שונים יש יכולות ומגבלות שונות.

באפשרותך לבדוק את הערוץ שמ ממנו קיבלת את הפעילות על-ידי בדיקת המאפיין channelId ב- Activity.

ערוצים כוללים נתונים ספציפיים שאינם תואמים למטען הכללי Activity בכל הערוצים. באפשרותך לגשת לנתונים אלה מהמאפיין TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) על-ידי יציקה למשתנים לשימוש בקוד שלך.

הסעיפים הבאים מסכמים שיקולים בעת עבודה עם לקוחות נפוצים.

צוותי מיקרוסופט

• תומך בכרטיסים מסתגלים עשירות עם תכונות מתקדמות.
• תומך בעדכונים ומחיקות של הודעות.
• כולל נתוני ערוץ ספציפיים עבור תכונות Teams, כגון אזכורים ופרטי פגישות.
• תומך בההפעלה של פעילויות עבור מודולי משימה.

Microsoft 365 Copilot

• התמקד בעיקר בפעילויות של הודעות.
• תומך בציטוטים ובפניות בתגובות.
• נדרשות תגובות זרימה.
• תמיכה מוגבלת בכרטיסים עשירים ובכרטיסים גמישים.

צ'אט באינטרנט/DirectLine

צ'אט באינטרנט הוא פרוטוקול HTTP שבו הסוכנים יכולים להשתמש כדי לקיים תקשורת באמצעות HTTPS.

• תמיכה מלאה עבור כל סוגי הפעילויות.
• תומך נתוני ערוץ מותאמים אישית.

ערוצים שאינם של Microsoft

ערוצים אלה כוללים את Slack, Facebook ועוד.

• ייתכן שיש תמיכה מוגבלת בסוגי פעילות מסוימים.
• עיבוד כרטיס עשוי להיות שונה או שאינו נתמך.
• בדוק תמיד את תיעוד הערוץ הספציפי.

‏‫השלבים הבאים‬

• למד אודות AgentApplication