Gérer les messages

Important

Vous devez faire partie du programme Frontier en version préliminaire pour obtenir un accès anticipé à Microsoft Agent 365. Frontier vous connecte directement aux dernières innovations d’IA de Microsoft. Les versions préliminaires Frontier sont soumises aux conditions existantes de vos contrats clients qui régissent les versions préliminaires. Comme ces fonctionnalités sont encore en cours de développement, leur disponibilité et leurs capacités peuvent évoluer au fil du temps.

En utilisant le Kit de développement logiciel (SDK) Agent 365, votre agent peut gérer des événements d’activité de plateforme tels que l’installation et la désinstallation, et envoyer plusieurs messages discrets à un seul tour. Cet article traite des modèles clés pour répondre aux utilisateurs et les tenir informés pendant que votre agent traite les demandes.

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

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

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

Contrairement aux gestionnaires de notification, le InstallationUpdate gestionnaire ne nécessite pas d’authentification, car l’événement d’installation ou de désinstallation se déclenche avant ou après que l’utilisateur a une session active.

Inscrire le gestionnaire d’installation et de désinstallation

Inscrivez un gestionnaire d’activités pour le type d’activité InstallationUpdate dans l’initialisation de votre agent :

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 définie "add" lorsque vous installez l’agent ou "remove" lorsque vous le désinstallez. Activity.from_property est une instance 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 une énumération des constantes de type d’activité importées à partir de @microsoft/agents-activity. Activity.action est une chaîne définie 'add' lorsque vous installez l’agent ou 'remove' lorsque vous le désinstallez.

.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 énumération de constantes de type d’activité. InstallationUpdateActionTypes fournit les constantesAdd et Remove pour comparer l'action d'activité.

Note

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

Envoyer plusieurs messages

Les agents 365 peuvent envoyer plusieurs messages discrets en réponse à une invite d’utilisateur unique. Pour ce faire, appelez SendActivityAsync (.NET), send_activity (Python) ou sendActivity (JavaScript) plusieurs fois au sein d’un seul tour.

Important

Teams ne prend pas en charge les réponses en flux continu pour les identités agentes. Le Kit de développement logiciel (SDK) détecte l'identité agentique et met le flux en mémoire tampon dans un seul message. Utilisez SendActivityAsync, send_activityou sendActivity directement pour envoyer des messages immédiats et discrets à l’utilisateur.

Les exemples suivants illustrent le modèle en envoyant un accusé de réception immédiat avant la réponse 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’exemple illustre ce modèle dans (on_message) en envoyant un accusé de réception immédiat avant la réponse 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 modèle dans le gestionnaire d’activités de message (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 modèle dans OnMessageAsync (MyAgent.cs).

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

Indicateurs de saisie

Les indicateurs de saisie montrent une ... animation d'avancement dans Teams :

• Ils ont un délai d’expiration visuel intégré d’environ 5 secondes et doivent être actualisés dans une boucle autour de toutes les quatre secondes.
• Ils ne sont visibles que dans les conversations un-on-one et les conversations de petit groupe, et non dans les canaux.

L’agent envoie des indicateurs de saisie dans une boucle autour de toutes les quatre secondes pour maintenir 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) { }
}