Gérer les messages

Avec le SDK Agent 365, votre assistant peut traiter les événements d’activité de la plateforme tels que l’installation et la désinstallation, et envoyer plusieurs messages distincts au cours d’un même tour. Cet article présente les principaux schémas pour répondre aux utilisateurs et les tenir informés pendant que votre assistant traite les demandes.

Gérer les événements d’installation et de désinstallation de l’assistant

Lorsqu’un utilisateur installe ou désinstalle votre assistant dans Teams ou d’autres canaux hébergés par Agent 365, la plateforme envoie une activité InstallationUpdate (également appelée événement agentInstanceCreated). Votre assistant peut gérer ces événements pour envoyer un message de bienvenue lors de l’installation et un message d’adieu lors de la désinstallation.

Action	Description
add	L’utilisateur installe l’assistant
remove	L’utilisateur désinstalle l’assistant

À la différence des gestionnaires de notification, le gestionnaire InstallationUpdate ne requiert pas d’authentification, car l’événement d’installation ou de désinstallation survient avant ou après que l’utilisateur ait une session active.

Enregistrez le gestionnaire d’installation et de désinstallation

Enregistrez un gestionnaire d’activité pour le type d’activité InstallationUpdate dans l’initialisation de votre assistant :

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 est une chaîne de caractères définie sur "add" lorsqu’un assistant est installé, ou sur "remove" lorsqu’il est désinstallé. Activity.from_property est une instance de ChannelAccount contenant l’identité de l’utilisateur.

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 est un enum de constantes de type d’activité importées depuis @microsoft/agents-activity. Activity.action est une chaîne de caractères définie sur 'add' lorsqu’un assistant est installé, ou sur 'remove' lorsqu’il est désinstallé.

.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 est une enum de constantes de types d’activité. InstallationUpdateActionTypes fournit les constantes Add et Remove pour comparer l’action d’activité.

Note

Pour .NET, inscrivez le gestionnaire deux fois : une fois avec isAgenticOnly: true pour le trafic Agent 365 en production avec des gestionnaires d’authentification agentiques facultatifs, et une fois avec isAgenticOnly: false pour les tests locaux avec Agents Playground ou WebChat.

Envoyer plusieurs messages

Les assistants Agent 365 peuvent envoyer plusieurs messages distincts en réponse à une seule requête utilisateur. Pour ce faire, appelez SendActivityAsync (.NET), send_activity (Python) ou sendActivity (JavaScript) à plusieurs reprises lors d’un seul tour.

Important

Teams ne prend pas en charge les réponses en streaming pour les identités agentiques. Le SDK détecte l’identité de l’assistant et regroupe le flux en un seul message. Utilisez SendActivityAsync, send_activity ou sendActivity directement pour envoyer des messages immédiats et discrets à l’utilisateur.

Les exemples suivants illustrent le schéma en envoyant un accusé de réception immédiat avant la réponse du 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’échantillon démontre ce schéma dans on_message (host_agent_server.py) en envoyant un accusé de réception immédiat avant la réponse du 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’exemple illustre ce schéma dans le gestionnaire d’activité de messages (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’exemple illustre ce schéma dans OnMessageAsync (MyAgent.cs).

Chaque appel à sendActivity, send_activity ou SendActivityAsync crée un message distinct. Vous pouvez l’appeler autant de fois que nécessaire pour envoyer des mises à jour de l’avancement, des résultats partiels ou une réponse finale.

Indicateurs de saisie

Les indicateurs de saisie indiquent une ... animation de progression dans Teams :

• Ils disposent d’un délai visuel intégré d’environ 5 secondes, qui doit être rafraîchi en boucle toutes les quatre secondes.
• Ils ne sont visibles que dans les conversations individuelles et les petits groupes, pas dans les canaux.

Toutes les quatre secondes, l’assistant envoie des indicateurs de saisie pour garder l’...animation active pendant que le LLM traite la requête :

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