Mesajları Ele Al

Agent 365 SDK'yi kullanarak, aracınınız platform etkinliklerini (örneğin yükleme ve kaldırma) işleyebilir ve tek bir turda birden fazla ayrı mesaj gönderebilir. Bu makale, aracınınız istekleri işlerken kullanıcılara yanıt verme ve onları bilgilendirme için temel yöntemleri açıklar.

Aracı kurulum ve kaldırma etkinliklerini yönetin

Bir kullanıcı, aracınınızı Teams veya diğer Agent 365 tarafından barındırılan kanallarda yüklediğinde veya kaldırdığında, platform bir InstallationUpdate etkinliği (aynı zamanda agentInstanceCreated olayı olarak da bilinir) gönderir. Aracınınız, kurulduğunda bir hoş geldiniz mesajı ve kaldırıldığında bir veda mesajı göndermek için bu olayları işleyebilir.

Eylem	Açıklama
add	Kullanıcı aracıı yükler
remove	Kullanıcı aracıı kaldırır

Bildirim işleyicilerinin aksine, InstallationUpdate işleyicisi kimlik doğrulaması gerektirmez çünkü yükleme veya kaldırma olayı, kullanıcının aktif bir oturumu olduktan önce veya sonra tetiklenir.

Kurulum ve kaldırma işleyicisini kaydedin

Aracınızın başlatılması sırasında InstallationUpdate etkinlik türü için bir etkinlik işleyicisi kaydedin:

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, aracı yüklediğinizde "add" veya kaldırdığınızda "remove" değerine ayarlanmış bir dizedir. Activity.from_property, kullanıcının kimliğini içeren bir ChannelAccount nesnesidir.

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 içinden import edilen etkinlik tipi sabitlerinden oluşan bir sabit listesisidir. Activity.action, aracı yüklediğinizde 'add' veya kaldırdığınızda 'remove' değerine ayarlanmış bir dizedir.

.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, etkinlik tipi sabitlerinden oluşan bir enumdur. InstallationUpdateActionTypes, etkinlik eylemini karşılaştırmak için Add ve Remove sabitlerini sağlar.

Not

.NET için, işleyiciyi iki kez kaydedin — bir kez isAgenticOnly: true üretim Agent 365 trafiği (isteğe bağlı agentik kimlik doğrulama yöneticileriyle) için, bir kez isAgenticOnly: false yerel test (Agents Playground veya WebChat ile) için.

Birden fazla mesaj gönderin

Agent 365 aracıları, tek bir kullanıcı istemine yanıt olarak birden fazla ayrı mesaj gönderebilir. Bunu yapmak için, tek bir tur içinde SendActivityAsync (.NET), send_activity (Python) veya sendActivity (JavaScript) yöntemini birden fazla kez çağırın.

Önemli

Teams, aracı kimlikleri için akış yanıtlarını desteklemez. SDK, aracı kimliğini algılar ve akışı tek bir mesaja tamponlar. Kullanıcıya anında, birbirinden bağımsız mesajlar göndermek için SendActivityAsync, send_activity veya sendActivity'ü doğrudan kullanın.

Aşağıdaki örnekler, LLM yanıtından önce anında bir onay göndererek bu deseni göstermektedir:

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)

Örnek, on_message (host_agent_server.py dosyasında) LLM yanıtından önce anında bir onay göndererek bu modeli göstermektedir.

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);

Bu örnek, bu deseni mesaj aktivite işleyicisinde (agent.ts) göstermektedir.

.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);

Örnek, bu deseni OnMessageAsync (MyAgent.cs) dosyasında göstermektedir.

Her çağrı sendActivity, send_activity veya SendActivityAsync ayrı bir mesaj oluşturur. İlerleme güncellemeleri, kısmi sonuçlar veya nihai bir yanıt göndermek için bu fonksiyonu dilediğiniz kadar çağırabilirsiniz.

Yazma göstergeleri

Teams'teki yazma göstergeleri bir ... ilerleme animasyonu gösterir:

• Yaklaşık 5 saniyelik yerleşik görsel zaman aşımına sahip ve bu süre her dört saniyede bir döngüde yenilenmesi gerekiyor.
• Yalnızca bire bir sohbetlerde ve küçük grup sohbetlerinde görünürler, kanallarda görünmezler.

Aracı, LLM isteği işlenirken ... animasyonunun aktif kalmasını sağlamak için yaklaşık her dört saniyede bir döngü halinde yazma göstergeleri gönderir:

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