Gestionar mensajes

Importante

Debe formar parte del programa de versión preliminar Frontier para obtener acceso anticipado a Microsoft Agent 365. Frontier te conecta directamente con las últimas innovaciones de IA de Microsoft. Las previsualizaciones de Frontier están sujetas a los términos de previsualización existentes de sus acuerdos con clientes. Dado que estas características siguen en desarrollo, su disponibilidad y funcionalidades pueden cambiar con el tiempo.

Mediante el SDK del Agente 365, el agente puede controlar eventos de actividad de plataforma, como instalar y desinstalar, y enviar varios mensajes discretos dentro de un solo turno. En este artículo se tratan los patrones clave para responder a los usuarios y mantenerlos informados mientras el agente procesa las solicitudes.

Controlar eventos de instalación y desinstalación del agente

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

Acción	Descripción
add	El usuario instala el agente.
remove	El usuario desinstala el agente.

A diferencia de los controladores de notificaciones, el InstallationUpdate controlador no requiere autenticación porque el evento de instalación o desinstalación se desencadena antes o después de que el usuario tenga una sesión activa.

Registro del controlador de instalación y desinstalación

Registre un controlador de actividad para el tipo de actividad InstallationUpdate en la inicialización del 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 establecida en "add" al instalar el agente o "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 establecida en 'add' al instalar el agente o '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 vez con isAgenticOnly: true para el tráfico del Agente de producción 365 con controladores de autenticación agente opcionales y una vez con isAgenticOnly: false para pruebas locales con Agents Playground o WebChat.

Envío de varios mensajes

Los agentes del agente 365 pueden enviar varios mensajes discretos en respuesta a un único mensaje de usuario. Para ello, llame a SendActivityAsync (.NET), send_activity (Python) o sendActivity (JavaScript) varias veces en 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. Use SendActivityAsync, send_activityo sendActivity directamente para enviar mensajes inmediatos y discretos al usuario.

En los ejemplos a continuación se muestra el patrón mediante el envío de una confirmación inmediata antes de la respuesta 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)

En el ejemplo se muestra este patrón en on_message (host_agent_server.py) mediante el envío de una confirmación inmediata antes de la respuesta de 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);

En el ejemplo se muestra este patrón en el controlador de actividad del mensaje (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);

En el ejemplo se muestra este patrón en OnMessageAsync (MyAgent.cs).

Cada llamada a sendActivity, send_activityo SendActivityAsync crea un mensaje independiente. Puede llamarlo 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 espera visual integrado de aproximadamente 5 segundos y que se deben actualizar en un bucle cada cuatro segundos.
• Solo son visibles en chats individuales y en chats de grupos pequeños, no en canales.

El agente envía indicadores de escritura cada cuatro segundos en un ciclo 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) { }
}