Gestire i messaggi

Importante

Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette ai termini di anteprima esistenti dei tuoi accordi con il cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la loro disponibilità e capacità potrebbero cambiare nel tempo.

Usando Agent 365 SDK, l'agente può gestire eventi di attività della piattaforma, ad esempio l'installazione e la disinstallazione, e inviare più messaggi discreti all'interno di un singolo turno. Questo articolo illustra i modelli chiave per rispondere agli utenti e mantenerli informati durante l'elaborazione delle richieste dell'agente.

Gestire gli eventi di installazione e disinstallazione dell'agente

Quando un utente installa o disinstalla l'agente in Teams o in altri canali ospitati da Agent 365, la piattaforma invia un'attività InstallationUpdate (detta anche evento agentInstanceCreated). L'agente può gestire questi eventi per inviare un messaggio di benvenuto quando è installato e un messaggio di saluto quando viene disinstallato.

Action	Descrizione
add	L'utente installa l'agente
remove	L'utente disinstalla l'agente

A differenza dei gestori di notifica, il InstallationUpdate gestore non richiede l'autenticazione perché l'evento di installazione o disinstallazione viene attivato prima o dopo che l'utente ha una sessione attiva.

Registrare il gestore di installazione e disinstallazione

Registrare un gestore di attività per il tipo di attività InstallationUpdate durante l'inizializzazione dell'agente.

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 è una stringa impostata su "add" quando si installa l'agente o "remove" quando la si disinstalla. Activity.from_property è un'istanza ChannelAccount contenente l'identità dell'utente.

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 è un'enumerazione delle costanti del tipo di attività importate da @microsoft/agents-activity. Activity.action è una stringa impostata su 'add' quando si installa l'agente o 'remove' quando la si disinstalla.

.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 è un'enumerazione delle costanti del tipo di attività. InstallationUpdateActionTypes fornisce le costanti Add e Remove per confrontare l'azione di attività.

Annotazioni

Per .NET, registrare il gestore due volte, una volta con isAgenticOnly: true per il traffico di Agent 365 in produzione con gestori opzionali di autenticazione agenti e una volta con isAgenticOnly: false per i test locali con Agents Playground o WebChat.

Inviare più messaggi

Gli agenti di Agent 365 possono inviare più messaggi discreti in risposta a una richiesta di un singolo utente. A tale scopo, chiamare SendActivityAsync (.NET), send_activity (Python) o sendActivity (JavaScript) più volte all'interno di un singolo turno.

Importante

Teams non supporta le risposte in streaming per le identità agentiche. L'SDK rileva l'identità agente e memorizza nel buffer il flusso in un singolo messaggio. Usare SendActivityAsync, send_activityo sendActivity direttamente per inviare messaggi immediati e discreti all'utente.

Gli esempi seguenti illustrano il modello inviando un riconoscimento immediato prima della risposta LLM:

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)

L'esempio illustra questo modello in on_message (host_agent_server.py) inviando un riconoscimento immediato prima della risposta LLM.

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

L'esempio illustra questo modello nel gestore dell'attività del messaggio (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);

L'esempio illustra questo modello in OnMessageAsync (MyAgent.cs).

Ogni chiamata a sendActivity, send_activityo SendActivityAsync crea un messaggio separato. È possibile chiamarlo quante volte necessario per inviare aggiornamenti dello stato di avanzamento, risultati parziali o una risposta finale.

Indicatori di digitazione

Gli indicatori di digitazione mostrano un'animazione di avanzamento ... in Teams.

• Hanno un timeout visivo predefinito di circa 5 secondi e che deve essere aggiornato in un ciclo ogni quattro secondi.
• Sono visibili solo nelle chat one-on-one e nelle chat di gruppo di piccole dimensioni, non nei canali.

L'agente invia indicatori di digitazione in un ciclo ogni quattro secondi per mantenere attiva l'animazione ... mentre LLM elabora la richiesta:

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