จัดการข้อความ

ด้วยการใช้ 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 เป็น 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 เป็น enum ของค่าคงที่ประเภทกิจกรรม InstallationUpdateActionTypes ให้ค่าคงที่ Add และ Remove เพื่อใช้ในการเปรียบเทียบการกระทำของกิจกรรม

หมายเหตุ

สำหรับ .NET ให้ลงทะเบียน handler สองครั้ง — ครั้งหนึ่งกับ 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) { }
}