טיפול בהודעות

בעזרת ערכת הפיתוח של Agent 365, הסוכן יוכל לטפל באירועי פעילות בפלטפורמה, כגון התקנה והסרה ואף לשלוח מספר הודעות נפרדות בתור אחד. מאמר זה סוקר את הדפוסים המרכזיים בעת מתן מענה למשתמשים ולעדכן משתמשים בעת שהסוכן מעבד בקשות.

ניהול אירועי התקנה והסרה של סוכן

כשמשתמש מתקין או מסיר את הסוכן ב-Teams או בערוצים אחרים שמאוחסנים ב-Agent 365, הפלטפורמה שולחת InstallationUpdate פעילות (שמכונה גם אירוע agentInstanceCreated). הסוכן יוכל לטפל באירועים כאלה כדי לשלוח הודעת ברכה במהלך ההתקנה והודעת פרידה בעת הסרת הסוכן.

פעולה	Description
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 הוא enum של קבועי סוגי פעילות שיובאו מ-@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 עבור בדיקה מקומית עם סביבת ארגז חול של סוכנים או עם 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) { }
}