إرسال حدث أو نشاط

يوفر Copilot Studio مجموعة من العقد التي يمكنك استخدامها للأنشطة التي ليست رسائل: عقدة Event، ونشاط Invoke والعقد الأخرى المتعلقة بالنشاط التي يدعمها بروتوكول activity.

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

بروتوكول activity هو مفهوم نقل أساسي في Copilot Studio. يسمح بروتوكول النشاط بالاتصال السلس بين المستخدمين والوكلاء. وهو يحدد هيكلا موحدا لجميع التفاعلات، وتصنيفها إلى أنواع مختلفة من الأنشطة.

تعد أنشطة الحدث وأنشطة الرسائل نوعين متميزين داخل بروتوكول النشاط، كل منها يخدم أغراضا فريدة في مهام سير عمل الاتصال.

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

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

إرسال الأحداث

تم تصميم عقدة نشاط الحدث لإرسال أنشطة الحدث. يتم إرسال أنشطة الحدث من الوكيل ويمكن اعتراضها واستخدامها من قبل القناة، التي تقرر ما إذا كان سيتم استخدام الأنشطة وكيفية استخدامها. عند إرسال حدث، يمكنك تسميته ثم يمكنك تعيين قيمة للحدث. يمكن أن تكون هذه القيمة بأي تنسيق:

• قيمة حرفية بدائية
• مرجع متغير
• صيغة Power Fx.

يتم تسلسل القيمة كقيمة حرفية JSON وإضافتها إلى النشاط الصادر.

تتضمن استخدامات هذه العقدة ما يلي:

• تكوين عنصر تحكم Web Chat مخصص لمعالجة الأحداث المرسلة من العامل. على سبيل المثال، يمكنك البحث عن حدث يرجع من الوكيل واتخاذ إجراء على الصفحة. يوضح نموذج 04.api/c.incoming-activity-event في مستودع نماذج Web Chat Microsoft Bot Framework على GitHub كيفية عمل معالجة الأحداث.
• استخدم أنشطة الحدث للتحكم في خدمات تسجيل AudioCodes — على سبيل المثال، لبدء تسجيل المكالمات أو إيقافه. لمزيد من المعلومات، راجع تسجيل المكالمات.

استخدام أدوات العميل

أثناء التزامن، نوفر لنموذج اللغة مجموعة من الأدوات. يفكر معظم الناس في الأدوات على أنها الاتصال بأنظمة خارجية.

ومع ذلك، يمكننا أيضا استخدام أنشطة الحدث لتنفيذ أدوات من العميل.

عندما يقرر المنسق تنفيذ أداة عميل، يرسل العامل نشاط حدث إلى العميل، بما في ذلك المدخلات المحددة في الأداة.

يرسل العامل النشاط، ثم ينتظر العميل لتنفيذ الإجراء وإرجاع نتيجة. عند الانتهاء من العميل، يرسل نشاط حدث يحتوي على الاستجابة إلى الوكيل. يأخذ العامل هذه الاستجابة كاستجابة الأداة ويستمر في التنسيق.

عينة حمولات لأدوات العميل

لنفترض أن لدينا أداة عميل تسترد النص على شريحة PowerPoint.

المدخلات هي رقم الصفحة، والإخراج هو النص على الشريحة.

يمكن للعامل إرسال حمولة مثل:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "from": { 
        "id": "d9c0dcf9-4045-8062-535b-73fb4dfee954", 
        "role": 0 
    }, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "page": 5      
    } 
} 

بعد انتهاء العملية، يرسل العميل الوكيل حمولة تشبه:

{ 
    "type": "event", 
    "timestamp": 1738709828, 
    "name": "getSlideContent", 
    "replyToId": "f617c120-7b36-496a-a096-ac692efdad04", 
    "value": { 
        "content": "QA slide. Next steps"      
    } 
} 

إعداد أدوات العميل

هناك طريقتان لتسجيل أدوات العميل.

كجزء من محتوى موضوع العامل الخاص بك، يمكنك تسجيل إجراء مهمة عميل مخصص على الوكيل الخاص بك، باستخدام محرر التعليمات البرمجية.

على سبيل المثال:

description: this tool retrieves the content of a powerpoint slide 
schemaName: GetSlideContent 
    dialog: 
      kind: TaskDialog 
      action: 
        kind: InvokeClientTaskAction 
        clientActionInputSchema: 
          kind: Record 
          properties: 
            page: 
            displayName: Page Number 
            description: The number of the slide 
            isRequired: true 
              type: Number 
        clientActionResponseSchema: 
          kind: Record 
          properties: 
            content: 
            displayName: Slide Content 
            description: The content of the slide 
              type: String 

في بعض الأحيان، تكون الأدوات المتوفرة ديناميكية، بناء على سياق عميل الاستضافة. للسماح بمزيد من المرونة، يمكن للمصنيعين تعيين متغير نظام لتعيين أدوات العميل الأخرى التي يمكن استخدامها لهذه الجلسة ديناميكيا.

- kind: SetVariable 
  id: setVariable_76NZWK 
  variable: System.ClientPluginActions 
  value: |- 
    =[ 
      { 
        Description: "this tool retrieves the content of a powerpoint slide", 
        Identifier: "GetSlideContent", 
        Name: "GetSlideContent", 
        Response: {mode: "Generated"}, 
        Inputs: [ 
          { 
            Description: "The name of the menu for the form to launch", 
            IsAutomatic: true, 
            IsRequired: true, 
            Name: "Page Number", 
            PropertyName: "page", 
            Type: { 
              '$kind': "Number" 
            } 
          } 
        ], 
        Outputs: [ 
          { 
            Description: "The content of the slide", 
            Name: "Slide Content", 
            PropertyName: "content", 
            Type: { 
              '$kind': "String" 
            } 
          } 
        ] 
      } 
    ] 

إرسال أنواع الأنشطة الأخرى

بالإضافة إلى أنشطة الحدث، يمكنك إرسال أنشطة من أنواع أخرى باستخدام عقدة نشاط Invoke . أنواع الأنشطة التي يمكنك إرسالها هي مجموعة فرعية من الأنشطة المقدمة في مخطط Bot Framework - فئة أنواع النشاط. عند استخدام هذه العقدة، يمكنك اختيار نوع النشاط ثم تعيين اسم أو قيمة اختياريا.

الأنواع الشائعة هي:

• تؤدي الكتابة إلى إرسال نشاط كتابة، والذي يمكن أن تختاره القناة لالتقاط مؤشر الكتابة وإظهاره على العميل.
• يُستخدم Invoke واستجابة Invoke خصيصاً مع Microsoft Teams. يمكنك إنشاء موضوع باستخدام مشغل استدعاء لاعتراض استدعاء وارد من Teams، واستخدام عقدة نشاط استجابة استدعاء لإرسال استجابة مناسبة مرة أخرى إلى Teams.
• يرسل التسليم نشاط تسليم مع تحكم صريح في القيمة. يتم استخدام التسليم للقنوات الخارجية، مثل AudioCodes.

المحتوى ذو الصلة

• العمل مع المتغيرات العمومية
• تخصيص الشكل والمظهر للوكيل.