Manejar mensajes

Al utilizar el SDK de Agent 365, su agente puede gestionar eventos de actividad de la plataforma, como instalaciones y desinstalaciones, y enviar varios mensajes independientes en un mismo turno. En este artículo se describen los patrones clave para responder a los usuarios y mantenerlos informados mientras su agente tramita las solicitudes.

Gestionar los eventos de instalación y desinstalación del agente

Cuando un usuario instala o desinstala su agente en Teams u otros canales alojados por Agent 365, la plataforma envía una InstallationUpdate actividad (también conocida como el evento agentInstanceCreated). El agente puede manejar estos eventos para enviar un mensaje de bienvenida cuando se instala y un mensaje de despedida cuando se desinstala.

Acción	Description
add	El usuario instala el agente
remove	El usuario desinstala el agente

A diferencia de los controladores de notificaciones, el manejador InstallationUpdate no requiere autenticación porque el evento de instalación o desinstalación se activa antes de que el usuario inicie sesión o después de que la sesión haya finalizado.

Registrar el controlador de instalación y desinstalación

Registre un controlador de actividad para el tipo de actividad InstallationUpdate en la inicialización de su 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 es una cadena que se establece en "add" al instalar el agente o en "remove" al desinstalarlo. Activity.from_property es una instancia de ChannelAccount que contiene la identidad del usuario.

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 es una enumeración de constantes de tipo de actividad importadas de @microsoft/agents-activity. Activity.action es una cadena que se establece en 'add' al instalar el agente o en 'remove' al desinstalarlo.

.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 es una enumeración de constantes de tipo de actividad. InstallationUpdateActionTypes proporciona las constantes Add y Remove para comparar la acción de la actividad.

Nota

Para .NET, registre el controlador dos veces: una con isAgenticOnly: true para el tráfico de producción de Agent 365 con controladores de autenticación de agentes opcionales, y otra con isAgenticOnly: false para pruebas locales con Agents Playground o WebChat.

Enviar múltiples mensajes

Los agentes de Agent 365 pueden enviar múltiples mensajes discretos en respuesta a una única indicación del usuario. Para hacer esto, llame a SendActivityAsync (.NET), send_activity (Python) o sendActivity (JavaScript) varias veces dentro de un solo turno.

Importante

Teams no admite respuestas de streaming para identidades agentes. El SDK detecta la identidad agente y almacena en búfer la secuencia en un único mensaje. Utilice SendActivityAsync, send_activity o sendActivity directamente para enviar mensajes inmediatos y discretos al usuario.

Los siguientes ejemplos demuestran el patrón enviando una confirmación inmediata antes de la respuesta del 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)

El ejemplo demuestra este patrón en on_messagePython (host_agent_server.py) enviando una confirmación inmediata antes de la respuesta del 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);

El ejemplo demuestra este patrón en el controlador de actividad de mensajes (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);

El ejemplo demuestra este patrón en OnMessageAsync (MyAgent.cs).

Cada llamada a sendActivity, send_activity o SendActivityAsync crea un mensaje separado. Puede invocarlo tantas veces como sea necesario para enviar actualizaciones de progreso, resultados parciales o una respuesta final.

Indicadores de escritura

En Teams, los indicadores de escritura muestran una animación de progreso ...:

• Tienen un tiempo de expiración visual de unos 5 segundos y deben actualizarse en un ciclo aproximadamente cada cuatro segundos.
• Solo son visibles en chats uno a uno y en grupos pequeños, no en canales.

El agente envía indicadores de escritura cada cuatro segundos en un bucle para mantener la animación ... activa mientras LLM procesa la solicitud:

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