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

بروتوكول النشاط هو بروتوكول اتصال قياسي يستخدم عبر Microsoft في العديد من Microsoft SDKs والخدمات والعملاء. يُستخدم بروتوكول النشاط من قبل 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 SDK:

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

ملحوظة

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

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

أنواع النشاط

يحدد نوع النشاط ما يتطلبه باقي النشاط أو يتوقعه بين العملاء والمستخدمين والوكلاء.

يتضمن هذا ما يلي:

• رسالة
• تحديث المحادثة
• حدث
• استدعاء
• Typing

رسالة

نوع النشاط الشائع هو نوع الرسالة ل 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)
});

استدعاء

نوع Activity هو نوع معين من النشاط الذي يستدعيه العميل إلى عامل لتنفيذ أمر أو عملية. إنها ليست مجرد رسالة. تعد أمثلة هذه الأنواع من الأنشطة شائعة في Microsoft Teams ل task/fetch و task/submit. لا تدعم جميع القنوات هذه الأنواع من الأنشطة.

Typing

نوع الكتابة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، مع الاقتباسات بطرقهم الخاصة. يستخدمون خاصية Entities الخاصة ب Activity. يمكنك إضافة اقتباسات مع activity.Entities.Add وإضافة كائن جديد Entity يحتوي على تعريف محدد Citation استنادا إلى العميل الخاص بك. يتم تسلسله ككائن JSON يقوم العميل بإلغاء تسلسله بعد ذلك استنادا إلى كيفية عرضه في العميل. بشكل أساسي، المرفقات عبارة عن رسائل، ويمكن أن تشير الاقتباسات إلى المرفقات وهي كائن آخر يتم إرساله في Entities الحمولة Activity .

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

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

القنوات المختلفة لها قدرات وقيود مختلفة.

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

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

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

مايكروسوفت تيمز

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

Microsoft 365 Copilot

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

Web Chat/DirectLine

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

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

القنوات غير Microsoft

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

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

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

• تعرف على AgentApplication