معالجة الرسائل

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

معالجة أحداث تثبيت العامل وإلغاء تثبيته

عندما يقوم مستخدم بتثبيت عاملك أو إلغاء تثبيته في Teams أو قنوات أخرى مستضافة على Agent 365، يرسل InstallationUpdate النظام الأساسي نشاطا (يشار إليه أيضا بالحدث agentInstanceCreated ). يمكن للوكيل معالجة هذه الأحداث لإرسال رسالة ترحيب عند تثبيتها ورسالة وداع عند إلغاء تثبيتها.

الإجراء	الوصف
add	يقوم المستخدم بتثبيت العامل
remove	يقوم المستخدم بإلغاء تثبيت العامل

على عكس معالجات الإعلامات، InstallationUpdate لا يتطلب المعالج المصادقة لأن حدث التثبيت أو إلغاء التثبيت يبدأ قبل جلسة عمل نشطة أو بعد ذلك.

تسجيل معالج التثبيت وإلغاء التثبيت

تخصيص معالج للنشاط من نوع InstallationUpdate أثناء إعداد الوكيل الخاص بك:

Python

@agent_app.activity("installationUpdate")
async def on_installation_update(context: TurnContext, state: TurnState):
    action = context.activity.action
    from_prop = context.activity.from_property
    logger.info(
        "InstallationUpdate received — Action: '%s', DisplayName: '%s', UserId: '%s'",
        action or "(none)",
        getattr(from_prop, "name", "(unknown)") if from_prop else "(unknown)",
        getattr(from_prop, "id", "(unknown)") if from_prop else "(unknown)",
    )
    if action == "add":
        await context.send_activity("Thank you for hiring me! Looking forward to assisting you in your professional journey!")
    elif action == "remove":
        await context.send_activity("Thank you for your time, I enjoyed working with you.")

Activity.action عبارة عن سلسلة تم تعيينها إلى "add" عند تثبيت العامل أو "remove" عند إلغاء تثبيته. Activity.from_property هو مثيل ChannelAccount يحتوي على هوية المستخدم.

جافا سكريبت

// In your agent class constructor:
this.onActivity(ActivityTypes.InstallationUpdate, async (context: TurnContext, state: TurnState) => {
    await this.handleInstallationUpdateActivity(context, state);
});

// Handler method:
async handleInstallationUpdateActivity(context: TurnContext, state: TurnState): Promise<void> {
    const from = context.activity?.from;
    console.log(`InstallationUpdate received — Action: '${context.activity.action ?? "(none)"}', DisplayName: '${from?.name ?? "(unknown)"}', UserId: '${from?.id ?? "(unknown)"}'`);

    if (context.activity.action === 'add') {
        await context.sendActivity('Thank you for hiring me! Looking forward to assisting you in your professional journey!');
    } else if (context.activity.action === 'remove') {
        await context.sendActivity('Thank you for your time, I enjoyed working with you.');
    }
}

أنواع النشاط هي قائمة تعداد لثوابت نوع النشاط المستوردة من @microsoft/agents-activity. Activity.action عبارة عن سلسلة تم تعيينها إلى 'add' عند تثبيت العامل أو 'remove' عند إلغاء تثبيته.

.NET

// In your agent class constructor:
OnActivity(ActivityTypes.InstallationUpdate, OnInstallationUpdateAsync, isAgenticOnly: true, autoSignInHandlers: agenticInstallHandlers);
OnActivity(ActivityTypes.InstallationUpdate, OnInstallationUpdateAsync, isAgenticOnly: false);

// Handler method:
protected async Task OnInstallationUpdateAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
    _logger?.LogInformation(
        "InstallationUpdate received — Action: '{Action}', DisplayName: '{Name}', UserId: '{Id}'",
        turnContext.Activity.Action ?? "(none)",
        turnContext.Activity.From?.Name ?? "(unknown)",
        turnContext.Activity.From?.Id ?? "(unknown)");

    if (turnContext.Activity.Action == InstallationUpdateActionTypes.Add)
    {
        await turnContext.SendActivityAsync(MessageFactory.Text("Thank you for hiring me! Looking forward to assisting you in your professional journey!"), cancellationToken);
    }
    else if (turnContext.Activity.Action == InstallationUpdateActionTypes.Remove)
    {
        await turnContext.SendActivityAsync(MessageFactory.Text("Thank you for your time, I enjoyed working with you."), cancellationToken);
    }
}

أنواع النشاط هي قائمة تعداد لثوابت نوع النشاط. يوفر InstallationUpdateActionTypes الثوابت Add و Remove لمقارنة إجراء النشاط.

ملاحظة

بالنسبة لـ .NET، يجب تسجيل المعالج مرتين — مرة باستخدام isAgenticOnly: true لحركة مرور الإنتاج لوكيل 365 مع معالجات المصادقة الاختيارية، ومرة أخرى باستخدام isAgenticOnly: false للاختبار المحلي باستخدام Agents Playground أو WebChat.

إرسال رسائل متعددة

يمكن لوكلاء العامل 365 إرسال رسائل منفصلة متعددة استجابة لمطالبة مستخدم واحد. للقيام بذلك، اتصل SendActivityAsync (.NET) send_activity أو (Python) أو sendActivity (JavaScript) عدة مرات في دور واحد.

Important

لا يدعم Teams استجابات الدفق للهويات ذات التصرف الذاتي. يكتشف SDK الهوية الوكيلة ويخزن الدفق مؤقتا في رسالة واحدة. استخدم SendActivityAsyncأو send_activityأو sendActivity مباشرة لإرسال رسائل منفصلة فورية إلى المستخدم.

توضح الأمثلة التالية النمط عن طريق إرسال إقرار فوري قبل استجابة LLM:

Python

@agent_app.activity("message")
async def on_message(context: TurnContext, state: TurnState):
    # Message 1: immediate ack — reaches the user right away
    await context.send_activity("Got it — working on it…")

    # ... LLM processing ...

    # Message 2: the LLM response
    await context.send_activity(response)

يوضح النموذج هذا النمط في on_message (host_agent_server.py) عن طريق إرسال إقرار فوري قبل استجابة LLM.

جافا سكريبت

// Message 1: immediate ack — reaches the user right away
await context.sendActivity('Got it — working on it…');

// ... LLM processing ...

// Message 2: the LLM response
await context.sendActivity(modelResponse);

يوضح النموذج هذا النمط في معالج نشاط الرسالة (agent.ts).

.NET

// Message 1: immediate ack — reaches the user right away
await turnContext.SendActivityAsync(MessageFactory.Text("Got it — working on it…"), cancellationToken);

// ... LLM processing ...

// Message 2: the LLM response (via StreamingResponse, buffered into one message for Teams agentic)
await turnContext.StreamingResponse.EndStreamAsync(cancellationToken);

يوضح النموذج هذا النمط في OnMessageAsync (MyAgent.cs).

كل استدعاء إلى sendActivityأو send_activityأو SendActivityAsync ينشئ رسالة منفصلة. يمكنك استدعائه عدة مرات حسب الحاجة لإرسال تحديثات التقدم أو النتائج الجزئية أو الإجابة النهائية.

مؤشرات الكتابة

تظهر مؤشرات الكتابة رسومًا متحركة تدل على التقدم في Teams:

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

يرسل الوكيل مؤشرات الكتابة في دورة متكررة كل أربع ثوان للحفاظ على ... الأنيميشن نشطًا أثناء معالجة LLM للطلب.

Python

# Message 1: immediate ack — reaches the user right away
await context.send_activity("Got it — working on it…")

# Send typing indicator immediately (awaited so it arrives before the LLM call starts).
await context.send_activity(Activity(type="typing"))

# Background loop refreshes the "..." animation every ~4s (it times out after ~5s).
async def _typing_loop():
    try:
        while True:
            await asyncio.sleep(4)
            await context.send_activity(Activity(type="typing"))
    except asyncio.CancelledError:
        pass  # Expected on cancel.

typing_task = asyncio.create_task(_typing_loop())
try:
    response = await agent.process_user_message(...)
    await context.send_activity(response)
finally:
    typing_task.cancel()
    try:
        await typing_task
    except asyncio.CancelledError:
        pass

جافا سكريبت

let typingInterval: ReturnType<typeof setInterval> | undefined;
const startTypingLoop = () => {
    typingInterval = setInterval(async () => {
        await context.sendActivity(Activity.fromObject({ type: ActivityTypes.Typing }));
    }, 4000);
};
const stopTypingLoop = () => { clearInterval(typingInterval); };

startTypingLoop();
try {
    // ... LLM processing ...
} finally {
    stopTypingLoop();
}

.NET

// Typing indicator loop — refreshes every ~4s for long-running operations.
using var typingCts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
var typingTask = Task.Run(async () =>
{
    try
    {
        while (!typingCts.IsCancellationRequested)
        {
            await Task.Delay(TimeSpan.FromSeconds(4), typingCts.Token);
            await turnContext.SendActivityAsync(Activity.CreateTypingActivity(), typingCts.Token);
        }
    }
    catch (OperationCanceledException) { /* expected on cancel */ }
}, typingCts.Token);

try { /* ... do work ... */ }
finally
{
    typingCts.Cancel();
    try { await typingTask; } catch (OperationCanceledException) { }
}