Håndter meldinger

Ved å bruke Agent 365 SDK kan agenten din håndtere plattformaktivitetshendelser som installasjon og avinstallering, og sende flere diskrete meldinger i én samtaleomgang. Denne artikkelen dekker de viktigste mønstrene for å svare brukere og holde dem informert mens agenten din behandler forespørsler.

Håndtering av agentens installasjons- og avinstallasjonshendelser

Når en bruker installerer eller avinstallerer agenten din i Teams eller andre kanaler som hostes av Agent 365, sender plattformen en InstallationUpdate-aktivitet (også kalt agentInstanceCreated-hendelse). Agenten din kan håndtere disse hendelsene ved installasjon ved å sende en velkomstmelding, og ved avinstallasjon ved å sende en avskjedsmelding.

Handling	Description
add	Brukeren installerer agenten
remove	Brukeren avinstallerer agenten

I motsetning til varslingshåndterere krever ikke InstallationUpdate-håndtereren autentisering, fordi installasjons- eller avinstallasjonshendelsen utløses før eller etter at brukeren har en aktiv økt.

Registrer installasjons- og avinstallasjonshåndterer

Registrer en aktivitetshandler for InstallationUpdate aktivitetstypen i agentens initialisering:

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 er en streng som er satt til "add" når du installerer agenten eller "remove" når du avinstallerer den. Activity.from_property er en instans av ChannelAccount som inneholder brukerens identitet.

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 er en opplisting av aktivitetstypekonstanter importert fra @microsoft/agents-activity. Activity.action er en streng som er satt til 'add' når du installerer agenten eller 'remove' når du avinstallerer den.

.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 er en opplisting med aktivitetstypekonstanter. InstallationUpdateActionTypes gir Add og Remove konstanter for å sammenligne aktivitetshandlingen.

Notat

For .NET må du registrere handleren to ganger — først med isAgenticOnly: true for produksjonstrafikk for Agent 365 med valgfrie autentiseringshåndterere for agentidentitet, deretter med isAgenticOnly: false for lokal testing med Agents Playground eller WebChat.

Send flere meldinger

Agent 365-agenter kan sende flere separate meldinger som svar på én enkelt brukerspørsmål. For å gjøre dette, kall SendActivityAsync (.NET), send_activity (Python) eller sendActivity (JavaScript) flere ganger i løpet av én runde.

Viktig!

Teams støtter ikke strømming av svar for agentiske identiteter. SDK-en oppdager agentisk identitet og buffrer strømmen til én enkelt melding. Bruk SendActivityAsync, send_activity eller sendActivity direkte for å sende umiddelbare, enkeltstående meldinger til brukeren.

Følgende eksempler demonstrerer mønsteret ved å sende en umiddelbar bekreftelse før LLM-svaret:

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)

Eksempelet demonstrerer dette mønsteret i on_messagePython (host_agent_server.py) ved å sende en umiddelbar bekreftelse før LLM-svaret.

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

Eksempelet demonstrerer dette mønsteret i meldingsaktivitetshåndtereren (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);

Eksempelet demonstrerer dette mønsteret i OnMessageAsync (MyAgent.cs).

Hver gang du kaller sendActivity, send_activity eller SendActivityAsync, opprettes en egen melding. Du kan kalle den så mange ganger som nødvendig for å sende fremdriftsoppdateringer, delvise resultater eller et endelig svar.

Inntastingsindikatorer

Skriveindikatorer viser en ... fremdriftsanimasjon i Teams:

• De har en innebygd visuell timeout på omtrent 5 sekunder, og den må fornyes i en løkke omtrent hvert fjerde sekund.
• De er bare synlige i én-til-én-nettprater og små gruppenettprater, ikke i kanaler.

Agenten sender skriveindikatorer med intervaller på cirka fire sekunder for å holde ...-animasjonen synlig mens LLM-en behandler forespørselen:

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