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

باستخدام 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 يتضمن هوية المستخدم.

JavaScript

// 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.');
    }
}

ActivityTypes هي عدد مِنْ ثوابت نوع النشاط المستوردة مِنْ @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);
    }
}

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

إشعار

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

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

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

مهم

لا يدعم 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.

JavaScript

// 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

JavaScript

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) { }
}