Håndtering af beskeder

Ved at bruge Agent 365 SDK kan din agent håndtere platformshændelser som installation og afinstallation og sende flere separate beskeder i én omgang. Denne artikel præsenterer de vigtige fremgangsmåder for at svare til brugere og holde dem informerede, mens din agent behandler forespørgsler.

Håndter agent-installations- og afinstallationshændelser

Når en bruger installerer eller afinstallerer din agent i Teams eller andre Agent 365-hostede kanaler, sender platformen en InstallationUpdate aktivitet (også kaldet agentInstanceCreated hændelsen). Din agent kan håndtere disse hændelser ved at sende en velkomstbesked, når den er installeret, og en afskedsbesked, når den er afinstalleret.

Handling	Beskrivelse
add	Brugeren installerer agenten
remove	Brugeren afinstallerer agenten

I modsætning til notifikationshandlere kræver InstallationUpdate-handleren ikke godkendelse, fordi installations- eller afinstallationshændelsen udløses før eller efter brugeren har en aktiv session.

Registrer installations- og afinstallationshandleren

Registrer en aktivitetshandler for InstallationUpdate aktivitetstypen i din agents 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, der angives til "add", når du installerer agenten, eller til "remove", når du afinstallerer den. Activity.from_property er en ChannelAccount-forekomst, der indeholder brugerens 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 enum for aktivitetstypekonstanter, der er importeret fra @microsoft/agents-activity. Activity.action er en streng, der angives til 'add', når du installerer agenten, eller til 'remove', når du afinstallerer 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 enum for aktivitetstypekonstanter. InstallationUpdateActionTypes angiver konstanterne Add og Remove til sammenligning af aktivitetshandlingen.

Bemærk

For .NET skal du registrere handleren to gange – én gang med isAgenticOnly: true for produktionstrafik til Agent 365 med eventuelle agentgodkendelseshandlere, og én gang med isAgenticOnly: false til lokal test med Agents Playground eller WebChat.

Send flere beskeder

Agent 365-agenter kan sende flere individuelle beskeder som svar på en enkelt brugerprompt. For at gøre dette skal du kalde SendActivityAsync (.NET), send_activity (Python) eller sendActivity (JavaScript) flere gange inden for én enkelt tur.

Vigtigt

Teams understøtter ikke streamende svar for agentbaserede identiteter. SDK'en registrerer agentbaseret identitet og bufferer strømmen til en enkelt besked. Brug SendActivityAsync, send_activity eller sendActivity direkte til at sende øjeblikkelige, diskrete beskeder til brugeren.

Følgende eksempler viser, hvordan man sender en øjeblikkelig bekræftelse 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)

Eksemplet demonstrerer dette mønster i on_message (host_agent_server.py) ved at sende en øjeblikkelig bekræftelse 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);

Eksemplet demonstrerer dette mønster i meddelelsesaktivitetshandleren (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);

Eksemplet demonstrerer dette mønster i OnMessageAsync (MyAgent.cs).

Hvert kald til sendActivity, send_activity eller SendActivityAsync genererer en individuel besked. Du kan kalde den så mange gange, du har brug for, for at sende statusopdateringer, delvise resultater eller et endeligt svar.

Skriveindikatorer

Skriveindikatorer viser en ... fremdriftsanimation i Teams:

• De har en indbygget visuel timeout på cirka 5 sekunder, og den skal genopfriskes i en løkke omkring hvert fjerde sekund.
• De er kun synlige i private chats og små gruppechats, ikke i kanaler.

Agenten sender skrivningsindikatorer i en løkke cirka hvert fjerde sekund for at holde ... animationen i live, mens LLM'en behandler anmodningen:

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