הבנת פרוטוקול פעילות

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

מהי פעילות?

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

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

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

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

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

מאפיין‬	Description
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 הוא אובייקט חשוב שמשמש בכל תור שיחה ב-Microsoft 365 Agents 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: המצב עבור התור

סוגי פעילויות

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

הן כוללות:

• הודעה
• 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);
            }
        }
    }
})

אירועים

הסוג Event של 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)
});

הפעלה

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

ציטוטים

חשוב לדעת שקובץ מצורף וציטוט אינם אותו סוג אובייקט. לקוחות, כמו 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) על ידי העברתם למשתנים לשימוש בקוד שלך.

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

Microsoft Teams

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

Microsoft 365 Copilot

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

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

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

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

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

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

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

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

• מידע על AgentApplication