Tangani Pesan

Dengan menggunakan Agent 365 SDK, agen Anda dapat menangani event aktivitas platform seperti pemasangan dan pencopotan, serta mengirim beberapa pesan terpisah dalam satu giliran. Artikel ini menjelaskan pola-pola penting untuk merespons pengguna dan menjaga mereka tetap mendapat informasi selama agen Anda memproses permintaan.

Menangani event instalasi dan uninstall agen

Ketika pengguna menginstal atau menghapus instalasi agen Anda di Teams atau saluran lain yang dihosting oleh Agent 365, platform akan mengirimkan aktivitas InstallationUpdate (juga disebut sebagai peristiwa agentInstanceCreated). Agen Anda dapat menangani event ini untuk mengirim pesan selamat datang saat diinstal dan pesan perpisahan saat instalasi dihapus.

Tindakan	Deskripsi
add	Pengguna menginstal agen
remove	Pengguna menghapus instalasi agen

Berbeda dengan penanganan notifikasi, penanganan InstallationUpdate tidak memerlukan autentikasi karena peristiwa instalasi atau penghapusan terjadi sebelum atau setelah sesi aktif pengguna.

Daftarkan penanganan instalasi dan penghapusan

Daftarkan penangan aktivitas untuk tipe aktivitas InstallationUpdate dalam inisialisasi agen Anda:

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 adalah set string untuk "add" saat Anda menginstal agen atau "remove" saat Anda menghapus instalasi agen tersebut. Activity.from_property adalah instans ChannelAccount yang berisi identitas pengguna.

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 adalah enum konstanta jenis aktivitas yang diimpor dari @microsoft/agents-activity. Activity.action adalah set string untuk 'add' saat Anda menginstal agen atau 'remove' saat Anda menghapus instalasi agen tersebut.

.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 adalah enum dari konstanta jenis aktivitas. InstallationUpdateActionTypes menyediakan konstanta Add dan Remove untuk membandingkan aksi aktivitas.

Catatan

Untuk .NET, daftarkan handler dua kali: pertama dengan isAgenticOnly: true untuk lalu lintas produksi Agent 365 dengan penangan autentikasi agen opsional, dan kedua dengan isAgenticOnly: false untuk pengujian lokal dengan Agents Playground atau WebChat.

Mengirim beberapa pesan

Agent 365 dapat mengirim beberapa pesan terpisah sebagai respons terhadap satu perintah pengguna. Untuk melakukan ini, panggil SendActivityAsync (.NET), send_activity (Python), atau sendActivity (JavaScript) beberapa kali dalam satu putaran.

Penting

Teams tidak mendukung respons streaming untuk identitas agentik. SDK mendeteksi identitas agen dan menyangga aliran ke dalam satu pesan. Gunakan SendActivityAsync, send_activity, atau sendActivity secara langsung untuk mengirim pesan segera dan terpisah kepada pengguna.

Contoh berikut menunjukkan pola dengan mengirimkan konfirmasi langsung sebelum respons 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)

Sampel menunjukkan pola ini dalam on_message (host_agent_server.py) dengan mengirimkan pengakuan langsung sebelum respons 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);

Sampel menunjukkan pola ini di penanganan aktivitas pesan (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);

Contoh ini menunjukkan pola tersebut dalam OnMessageAsync (MyAgent.cs).

Setiap panggilan ke sendActivity, send_activity, atau SendActivityAsync membuat pesan terpisah. Anda dapat memanggilnya sebanyak yang diperlukan untuk mengirim pembaruan kemajuan, hasil parsial, atau jawaban akhir.

Indikator pengetikan

Indikator pengetikan menunjukkan ... animasi kemajuan di Teams:

• Indikator ini memiliki batas waktu visual bawaan sekitar 5 detik dan itu harus di-refresh dalam perulangan sekitar setiap empat detik.
• Indikator ini hanya terlihat dalam obrolan satu lawan satu dan obrolan grup kecil, bukan di saluran.

Agen mengirim indikator pengetikan secara berulang setiap empat detik untuk menjaga animasi ... tetap aktif selama LLM memproses permintaan:

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