فهم بروتوكول النشاط

بروتوكول النشاط هو بروتوكول اتصال معياري يُستخدم عبر Microsoft في العديد من حزم تطوير البرمجيات والخدمات والبرامج العميلة. يُستخدم Activity Protocol في Microsoft 365 Copilot، وMicrosoft Copilot Studio، وMicrosoft Teams، وMicrosoft 365 Agents SDK. بروتوكول النشاط يحدد بنية Activity وكيفية انتقال الرسائل والأحداث والتفاعلات من القناة إلى الكود الخاص بك وكل نقطة بينهما. يمكن للعاملين الاتصال بقناة أو أكثر للتفاعل مع المستخدمين والعمل مع عاملين آخرين. يوحّد بروتوكول النشاط بروتوكول الاتصال مع أي عميل تعمل معه، بما في ذلك عملاء Microsoft والعملاء غير التابعين لـ Microsoft، بحيث لا تحتاج إلى إنشاء منطق مخصص لكل قناة.

مَا المقصود بالنشَاط؟

Activity عبارة عن كائن JSON منظم يمثل أي تفاعل بين المستخدم وعامل. الأنشطة ليست مقتصرة على الرسائل النصية. يمكن أن تتضمن عدة أشكال من التفاعل، مثل الأحداث كانضمام أو مغادرة المستخدم (للمنصات التي تدعم عدة مستخدمين)، مؤشرات الكتابة، تحميل الملفات، تنفيذ إجراءات البطاقات، والأحداث المخصصة التي يبتكرها المطورون.

كل نشاط يتضمن بيانات وصفية حول:

• المرسل (من)
• من يجب أن يتلقاها (المستلم)
• سياق المحادثة
• القناة التي نشأ منها
• نوع التفاعل
• البيانات المحمّلة

مخطط بيانات النشاط - الخصائص الرئيسية

تحدد هذه المواصفة بروتوكول النشاط: بروتوكول النشاط - النشاط. بعض الخصائص الرئيسية المعرّفة في بروتوكول النشاط هي:

الخاصية	الوصف
Id	عادةً ما يتم توليدها بواسطة القناة إذا كان النشاط مصدره قناة.
Type	يحدد النوع معنى النشاط، على سبيل المثال نوع الرسالة.
ChannelID	يرمز الوسم ChannelID إلى القناة التي نشأ منها النشاط. على سبيل المثال: msteams.
From	مرسل النشاط (سواء كان مستخدمًا أو عاملًا)
Recipient	المستلم المقصود للنشاط
Text	محتوى نص الرسالة.‬
Attachment	محتوى غني مثل البطاقات، صور الملفات

الوصول إلى بيانات النشاط

لإكمال الإجراءات من الكائن TurnContext، يحتاج المطورون إلى الوصول إلى البيانات داخل النشاط.

يمكنك العثور على فئة TurnContext في كل نسخة لغوية من حزمة تطوير Microsoft 365 Agents:

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

إشعار

القصاصات البرمجية في هذا المقال تستخدم C#. تركيب الكود وهيكل واجهة برمجة التطبيقات في نسختي JavaScript وPython متشابهة.

هذا TurnContext هو عنصر مهم يستخدم في كل دور محادثة في حزمة تطوير Microsoft 365 Agents. يوفر الوصول إلى النشاط الوارد، وطرق إرسال الردود، وإدارة حالة المحادثة، والسياق اللازم للتعامل مع دورة واحدة من المحادثة. استخدمها للحفاظ على السياق، وإرسال الردود المناسبة، والتفاعل مع مستخدميك في عملائهم أو قنواتهم بفعالية. في كل مرة يتلقى عامل نشاطًا جديدًا من قناة، يقوم 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)
});

استدعاء

نوع الاستدعاء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 الحمولة.

اعتبارات خاصة بالقناة

تم بناء Microsoft 365 Agents SDK كمحور يستخدمه المطورون لإنشاء عاملين يمكنهم العمل مع أي عميل، بما في ذلك العملاء الذين ندعمهم. يوفر الأدوات للمطورين لبناء محول قناة خاص بهم باستخدام نفس الإطار البرمجي. توفر هذه البنية للمطورين خيارات واسعة فيما يتعلق بالعوامل، كما تتيح قابلية التوسعة للعملاء للاتصال بذلك المركز، والذي قد يكون واحداً أو أكثر مثل Microsoft Teams وSlack وغيرها.

تتمتع القنوات المختلفة بإمكانيات وقيود متباينة.

يمكنك التحقق من القناة التي استلمت منها النشاط من خلال فحص خاصية channelId في Activity.

تتضمن القنوات بيانات محددة لا تتوافق مع الحمولة العامة Activity عبر جميع القنوات. يمكنك الوصول إلى هذه البيانات من خاصية TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) عن طريق تحويلها إلى متغيرات لاستخدامها في الكود الخاص بك.

تلخص الأقسام التالية الاعتبارات عند التعامل مع العملاء العاديين.

Microsoft Teams

• يدعم بطاقات موائمة مفتوحة الغنية بميزات متقدمة.
• يدعم تحديثات الرسائل وحذفها.
• لديه بيانات قناة محددة لميزات Teams، مثل الإشارات ومعلومات الاجتماع.
• يدعم استدعاء الْأنشطة للوحدات الْنمطية للمهام.

Microsoft 365 Copilot

• يركز بشكل أساسي على أنشطة الرسائل.
• يدعم الاستشهادات والمراجع في الردود.
• يتطلب ردود متسلسلة.
• دعم محدود للبطاقات الغنية والبطاقات التكيفية.

Web Chat/DirectLine

Web Chat هي بروتوكول HTTP يمكن للوكلاء استخدامه للتواصل عبر HTTPS.

• الدعم الكامل لجميع أنواع الأنشطة.
• يدعم بيانات القناة المخصصة.

قنوات غير تابعة لـ Microsoft

تشمل هذه القنوات Slack وFacebook والمزيد.

• قد يكون هناك دعم محدود لأنواع معينة من الأنشطة.
• قد يكون عرض البطاقات مختلفًا أو غير مدعوم.
• دائمًا تحقق من دليل القناة المحددة.

الخطوات التالية

• اطلع على AgentApplication