Nachrichten verarbeiten

Durch die Verwendung des Agent 365 SDK kann Ihr Agent Plattform-Ereignisse wie Installation und Deinstallation handhaben und mehrere separate Nachrichten innerhalb eines einzigen Interaktionsschritts senden. Dieser Artikel behandelt die wichtigsten Muster, um auf Nutzer zu reagieren und sie während der Bearbeitung von Anfragen durch Ihren Agent auf dem Laufenden zu halten.

Agent-Installations- und -Deinstallationsereignisse verarbeiten

Wenn ein Benutzer Ihren Agent in Teams oder anderen von Agent 365 gehosteten Kanälen installiert oder deinstalliert, löst die Plattform eine InstallationUpdate-Aktivität aus (die auch als agentInstanceCreated-Ereignis bezeichnet wird). Ihr Agent kann diese Ereignisse verarbeiten, um bei der Installation eine Begrüßungsnachricht und bei der Deinstallation eine Abschiedsnachricht zu senden.

Aktion	Beschreibung des Daten-Flows
add	Der Benutzer installiert den Agent
remove	Der Benutzer deinstalliert den Agent

Im Gegensatz zu Benachrichtigungs-Handlern benötigt der InstallationUpdate Handler keine Authentifizierung, da das Installations- oder Deinstallationsereignis vor oder nach einer aktiven Sitzung des Benutzers ausgelöst wird.

Registrieren Sie den Handler für Installation und Deinstallation

Registrieren Sie einen Aktivitätshandler für den InstallationUpdate-Aktivitätstyp bei der Initialisierung Ihres Agents:

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 ist eine Zeichenkette, die auf "add" eingestellt ist, wenn Sie den Agent installieren oder auf "remove" wenn Sie ihn deinstallieren. Activity.from_property ist eine Instanz von ChannelAccount, die die Identität des Benutzers enthält.

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 ist eine Enumeration von Aktivitätstypkonstanten, die aus @microsoft/agents-activity importiert werden. Activity.action ist eine Zeichenkette, die auf 'add' eingestellt ist, wenn Sie den Agent installieren oder auf 'remove' wenn Sie ihn deinstallieren.

.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 ist eine Enumeration von Aktivitätstypkonstanten. InstallationUpdateActionTypes stellt die Konstanten Add und Remove zum Vergleich der Aktivitätsaktion bereit.

Anmerkung

Für .NET muss der Handler zweimal registriert werden: einmal mit isAgenticOnly: true für den Produktionsverkehr von Agent 365 mit optionalen agentischen Authentifizierungshandlern und einmal mit isAgenticOnly: false für lokale Tests mit Agents Playground oder WebChat.

Mehrere Nachrichten senden

Agents von Agent 365 können als Antwort auf einen einzelnen Benutzer-Prompt mehrere einzelne Nachrichten senden. Dazu rufen Sie SendActivityAsync (.NET), send_activity (Python) oder sendActivity (JavaScript) mehrmals innerhalb einer einzelnen Interaktion auf.

Wichtig

Teams unterstützt keine Streamingantworten für agentische Identitäten. Das SDK erkennt die Agentidentität und bündelt den Nachrichtenstrom zu einer einzigen Nachricht. Verwenden Sie SendActivityAsync, send_activity oder sendActivity direkt, um sofortige, diskrete Nachrichten an den Nutzer zu senden.

Die folgenden Beispiele zeigen diese Vorgehensweise, indem sie vor der LLM-Antwort eine sofortige Bestätigung senden:

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)

Das Beispiel zeigt dieses Muster in on_message (host_agent_server.py), indem eine sofortige Bestätigung vor der LLM-Antwort gesendet wird.

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

Das Beispiel demonstriert dieses Muster im Handler für Nachrichtenaktivitäten (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);

Das Beispiel demonstriert dieses Muster in OnMessageAsync (MyAgent.cs).

Mit jedem Aufruf von sendActivity, send_activity oder SendActivityAsync wird eine separate Nachricht erzeugt. Sie können sie beliebig oft aufrufen, um Fortschrittsupdates, Teilergebnisse oder eine endgültige Antwort zu senden.

Eingabeindikatoren

Eingabeindikatoren zeigen eine ...-Fortschrittsanimation in Teams an:

• Sie verfügen über ein integriertes visuelles Timeout von etwa 5 Sekunden, das alle vier Sekunden in einer Schleife aktualisiert werden muss.
• Sie sind nur in Einzelchats und kleinen Gruppenchats sichtbar, nicht in Kanälen.

Der Agent sendet etwa alle vier Sekunden Eingabeindikatoren in einer Schleife, um die ...-Animation live zu halten, während das LLM die Anforderung verarbeitet.

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