Hantera meddelanden

Genom att använda Agent 365 SDK kan din agent hantera plattformshändelser som installation och avinstallation, och skicka flera diskreta meddelanden under en och samma omgång. Den här artikeln beskriver de viktigaste metoderna för att svara användare och hålla dem informerade medan din agent behandlar förfrågningar.

Hantera installations- och avinstallationshändelser för agenten

När en användare installerar eller avinstallerar din agent i Teams eller andra kanaler som drivs av Agent 365, skickar plattformen en InstallationUpdate-aktivitet (även kallad agentInstanceCreated-händelse). Din agent kan hantera dessa händelser genom att skicka ett välkomstmeddelande när den är installerad och ett avskedsmeddelande när den avinstalleras.

Åtgärd	beskrivning
`add`	Användaren installerar agenten
`remove`	Användaren avinstallerar agenten

Till skillnad från notifikationshanterare kräver InstallationUpdate-hanteraren ingen autentisering eftersom installations- eller avinstallationshändelsen sker före eller efter att användaren har en engagerad session.

Registrera installations- och avinstallationshanteraren

Registrera en aktivitetshanterare för aktivitetstypen InstallationUpdate i din agents initialisering:

@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 är en sträng inställd på "add" när du installerar agenten eller "remove" när du avinstallerar den. Activity.from_property är en instans av ChannelAccount som innehåller användarens identitet.

// 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 är en uppräkning av aktivitetstypkonstanter importerade från @microsoft/agents-activity. Activity.action är en sträng inställd på 'add' när du installerar agenten eller 'remove' när du avinstallerar den.

// 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 är en uppräkning av aktivitetstypkonstanter. InstallationUpdateActionTypes innehåller konstanterna Add och Remove för att jämföra aktivitetsåtgärden.

Kommentar

För .NET, registrera hanteraren två gånger — en gång med isAgenticOnly: true för Agent 365-produktionstrafik med valfria autentiseringshanterare för agentidentiteter, och en gång med isAgenticOnly: false för lokal testning med Agents Playground eller WebChat.

Skicka flera meddelanden

Agent 365-agenter kan skicka flera separata meddelanden som svar på en enda användarprompt. För att göra detta, anropa SendActivityAsync (.NET), send_activity (Python) eller sendActivity (JavaScript) flera gånger inom samma omgång.

Viktigt

Teams stöder inte strömmande svar för agentiska identiteter. SDK:n upptäcker agentisk identitet och buffrar strömmen till ett enda meddelande. Använd SendActivityAsync, send_activity eller sendActivity direkt för att skicka omedelbara, diskreta meddelanden till användaren.

Följande exempel visar mönstret genom att skicka en omedelbar bekräftelse före LLM-svaret:

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

Exemplet demonstrerar detta mönster i on_message (host_agent_server.py) genom att skicka en omedelbar bekräftelse före LLM-svaret.

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

Exemplet demonstrerar detta mönster i meddelandeaktivitetshanteraren (agent.ts).

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

Exemplet demonstrerar detta mönster i OnMessageAsync (MyAgent.cs).

Varje anrop till sendActivity, send_activity eller SendActivityAsync skapar ett separat meddelande. Du kan anropa den så många gånger du behöver för att skicka framstegsuppdateringar, delresultat eller ett slutgiltigt svar.

Skrivindikatorer

Skrivindikatorer visar en ... framstegsanimation i Teams:

De har en inbyggd visuell timeout på cirka 5 sekunder och den måste uppdateras i en loop ungefär var fjärde sekund.
De syns bara i enskilda chattar och små gruppchattar, inte i kanaler.

Agenten skickar typindikatorer upprepade gånger, ungefär var fjärde sekund, för att hålla ...-animationen aktiv medan LLM bearbetar förfrågan:

# 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

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

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

Feedback

Var den här sidan till hjälp?

Last updated on 2026-07-30