Comparteix a través de

Notificar a agentes

Importante

Debe formar parte del programa de versión preliminar Frontier para obtener acceso anticipado a Microsoft Agent 365. Frontier le conecta directamente con las innovaciones de inteligencia artificial más recientes de Microsoft. Las versiones preliminares de Frontier están sujetas a los términos de vista previa existentes en tus acuerdos con clientes. Dado que estas características siguen en desarrollo, su disponibilidad y funcionalidades pueden cambiar con el tiempo.

Mediante el módulo Notificaciones, puede crear agentes que respondan a eventos y notificaciones de aplicaciones Microsoft 365. Mediante el soporte de notificaciones, los agentes pueden recibir y procesar alertas cuando los usuarios interactúan con ellos mediante correo electrónico, comentarios en documentos u otros escenarios colaborativos.

Flujo de trabajo de notificaciones

Siga este flujo de trabajo para habilitar las notificaciones de la aplicación del agente de IA:

  1. Instalar paquetes de notificación.

  2. Importar componentes de notificación

    • Importar clases y controladores de notificación.
    • Importe los tipos de actividad y los identificadores de canal.

  3. Registro de controladores de notificaciones

    • Use métodos de controlador de notificaciones para registrar rutas.
    • Configure controladores para tipos de notificación específicos, como correo electrónico, Word, Excel o PowerPoint.

  4. Procesamiento de notificaciones en el código del agente

    • El agente recibe notificaciones de aplicaciones Microsoft 365.
    • Controle las notificaciones entrantes y responda correctamente.

Tipos de notificación

El SDK del Agente 365 admite los siguientes tipos de notificaciones:

Tipo de notificación Descripción Identificador de sub canal
Correo electrónico El agente recibe un correo electrónico en el que se le menciona o se le dirige directamente. email
Word El agente se menciona en un comentario en un documento de Word word
Excel El agente se menciona en un comentario en un documento de Excel excel
PowerPoint El agente se menciona en un comentario en un documento de PowerPoint powerpoint
Eventos de ciclo de vida Notificaciones del ciclo de vida del agente (identidad de usuario creada, incorporación de cargas de trabajo, usuario eliminado) N/D

Eventos del ciclo de vida del agente

Los eventos de ciclo de vida del agente permiten al agente responder a eventos del sistema específicos relacionados con la administración de identidades de usuario agente. El SDK admite actualmente tres eventos de ciclo de vida:

Tipo de evento Id. de evento Descripción
Identidad de usuario creada agenticUserIdentityCreated Se desencadena cuando se crea una identidad de usuario agente
Actualización en la incorporación de cargas de trabajo agenticUserWorkloadOnboardingUpdated Se desencadena cuando se actualiza el estado de incorporación de carga de trabajo de un usuario agente
Usuario eliminado agenticUserDeleted Se desencadena cuando se elimina una identidad de usuario agente

Con estos eventos, los agentes pueden realizar tareas de inicialización, operaciones de limpieza o administración de estado en respuesta a los cambios en el ciclo de vida del usuario.

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.

@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" cuando el agente se instala o "remove" cuando se desinstala. Activity.from_property es una instancia de ChannelAccount que contiene la identidad del usuario.

Referencia de carga útil de notificación

Cuando tu agente recibe una notificación, la carga útil contiene datos estructurados específicos del tipo de notificación. Comprender estas cargas útiles te ayuda a extraer la información que necesitas para procesar las notificaciones de forma eficaz.

Carga útil de notificación por correo electrónico

Cuando un usuario envía un correo electrónico a tu agente o menciona a tu agente en un correo, este recibe una notificación por correo electrónico con la siguiente estructura:

{
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2026-02-06T17:45:20.740Z",
  "channelId": "agents",
  "serviceUrl": "http://localhost:56150/_connector",
  "recipient": {
    "id": "AgentName@contoso.onmicrosoft.com",
    "name": "My Agent",
    "agenticUserId": "<agentic-user-id>",
    "agenticAppId": "<agentic-app-id>",
    "tenantId": "<tenant-id>",
    "role": "agenticUser"
  },
  "conversation": {
    "id": "<conversation-id>",
    "conversationType": "personal",
    "tenantId": "<tenant-id>"
  },
  "from": {
    "id": "sender@contoso.onmicrosoft.com",
    "name": "Sender Name",
    "role": "user"
  },
  "type": "message",
  "channelData": {
    "tenant": {
      "id": "<tenant-id>"
    }
  },
  "locale": "en-US",
  "name": "emailNotification",
  "entities": [
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "emailNotification",
      "id": "<email-id>",
      "conversationId": "<conversation-id>",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\">Your email message content here</div>\n</body>"
    }
  ]
}

Carga de notificación de comentarios de documentos (Word, Excel, PowerPoint)

Cuando un usuario menciona al agente en un comentario dentro de un documento de Word, Excel o PowerPoint, el agente recibe una notificación de comentario de WPX (Word, PowerPoint, Excel):

{
  "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "timestamp": "2026-02-06T17:46:02.248Z",
  "channelId": "agents",
  "serviceUrl": "http://localhost:56150/_connector",
  "recipient": {
    "id": "AgentName@contoso.onmicrosoft.com",
    "name": "My Agent",
    "agenticUserId": "<agentic-user-id>",
    "agenticAppId": "<agentic-app-id>",
    "tenantId": "<tenant-id>",
    "role": "agenticUser"
  },
  "conversation": {
    "id": "<conversation-id>",
    "conversationType": "personal",
    "tenantId": "<tenant-id>",
    "topic": "<document-topic>"
  },
  "from": {
    "id": "sender@contoso.onmicrosoft.com",
    "name": "Sender Name",
    "role": "user"
  },
  "type": "message",
  "channelData": {
    "tenant": {
      "id": "<tenant-id>"
    },
    "productContext": "Word"
  },
  "locale": "en-US",
  "textFormat": "plain",
  "text": "<at>My Agent</at> - Please review this section\n",
  "attachments": [
    {
      "contentUrl": "<document-url>",
      "name": "<document-name>",
      "content": {
        "uniqueId": "<document-unique-id>",
        "fileType": "docx"
      },
      "contentType": "application/vnd.microsoft.teams.file.download.info"
    }
  ],
  "entities": [
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "mentioned": {
        "id": "AgentName@contoso.onmicrosoft.com",
        "name": "@My Agent"
      },
      "text": "<at>My Agent</at>",
      "type": "mention"
    },
    {
      "id": "Word",
      "type": "productInfo"
    },
    {
      "parentCommentId": "<parent-comment-id>",
      "commentId": "<comment-id>",
      "documentId": "<document-id>",
      "type": "wpxcomment"
    }
  ]
}

Añade notificaciones a tu agente

Siga estos pasos para habilitar el control de notificaciones en el agente existente:

Importar componentes de notificación

Agregue estas importaciones al archivo del agente:

from microsoft_agents_a365 import AgentApplication
from microsoft_agents_a365.notifications import (
    AgentNotification,
    AgentNotificationActivity,
    NotificationTypes
)
from microsoft_agents.activity import ChannelId
from microsoft_agents.hosting.core import Authorization, TurnContext
  • AgentApplication: clase base para compilar aplicaciones Agent365. Proporciona una funcionalidad básica para enrutar actividades, administrar el estado y procesar solicitudes.
  • AgentNotification: clase para registrar controladores de notificaciones con métodos de decorador. Proporciona on_agent_notification(), on_email(), on_word() y otros decoradores útiles.
  • AgentNotificationActivity: contenedor que contiene datos de notificación analizados con propiedades tipadas como email_notification y wpx_comment_notification que contienen metadatos específicos de la notificación, como identificadores, detalles de conversación y referencias a documentos.
  • NotificationTypes: enumeración de tipos de notificación admitidos como EMAIL_NOTIFICATION, WPX_COMMENT.
  • ChannelId: use para especificar canales de notificación, por ejemplo, ChannelId(channel="agents", sub_channel="*").
  • Autorización: contexto de autorización para procesar notificaciones.
  • TurnContext: contexto del turno de conversación actual del SDK de agentes.

Registra los controladores de notificaciones en tu agente

Agregue controladores de notificaciones a la inicialización del agente:

class YourAgent(AgentApplication):
    def __init__(self, app):
        # Create notification handler
        agent_notification = AgentNotification(app)
        
        # Register handler for all notifications
        @agent_notification.on_agent_notification(
            ChannelId(channel="agents", sub_channel="*")
        )
        async def handle_all_notifications(context, state, notification):
            # Route based on notification type
            if notification.notification_type == NotificationTypes.EMAIL_NOTIFICATION:
                await self.handle_email_notification(context, state, notification)
            elif notification.notification_type == NotificationTypes.WPX_COMMENT:
                await self.handle_comment_notification(context, state, notification)
            else:
                await context.send_activity('Notification type not yet implemented.')

Implementación de controladores de notificaciones específicos

Agregue métodos de controlador para cada tipo de notificación:

class YourAgent(AgentApplication):
    # ... __init__ from above ...
    
    async def handle_email_notification(self, context, state, notification):
        """Handle email notifications"""
        email = notification.email_notification
        
        if not email:
            await context.send_activity('No email data found')
            return
        
        # Process the email
        await context.send_activity(
            f'Received email notification. Email ID: {email.id}'
        )
        
        # Your email processing logic here
    
    async def handle_comment_notification(self, context, state, notification):
        """Handle document comment notifications"""
        comment = notification.wpx_comment_notification
        
        if not comment:
            await context.send_activity('No comment data found')
            return
        
        # Process the comment
        await context.send_activity(
            f'Received comment notification. Document ID: {comment.document_id}'
        )
        
        # Your comment processing logic here

Identificación del remitente

Cada actividad de notificación incluye Activity.From. La plataforma A365 rellena esta propiedad con la identidad básica del remitente, por lo que no necesita ninguna llamada API ni adquisición de tokens. Acceda a él dentro de cualquier controlador de notificaciones:

async def handle_email_notification(self, context, state, notification):
    from_prop = context.activity.from_property
    logger.info(
        "Notification from — DisplayName: '%s', UserId: '%s', AadObjectId: '%s'",
        getattr(from_prop, "name", None) or "(unknown)",
        getattr(from_prop, "id", None) or "(unknown)",
        getattr(from_prop, "aad_object_id", None) or "(none)",
    )
    display_name = getattr(from_prop, "name", None) or "unknown"
    # Use display_name in your response or LLM prompt

Activity.from_property es una instancia de clase ChannelAccount que tiene las siguientes propiedades:

Propiedad Descripción
name Nombre para mostrar
id Identificador de usuario del canal
aad_object_id ID de objeto Entra

Importante

El nombre para mostrar es texto controlado por el usuario. Sanitiza (elimina los caracteres de control, aplica una longitud máxima) antes de insertarlo en las indicaciones del sistema LLM para evitar ataques de inyección de órdenes.

Sugerencia

Use aadObjectId con Microsoft Graph API para recuperar datos de perfil extendidos (puesto, administrador, departamento) cuando el agente tenga los permisos adecuados.

Controladores de notificaciones especializados

Después de configurar el enrutamiento de notificaciones básico, use métodos de controlador especializados para un control más granular. Mediante estos métodos, puede hacer lo siguiente:

  • Registre varios controladores para el mismo tipo de notificación.
  • Establezca la prioridad del controlador mediante la clasificación.
  • Configure la autenticación automática para cada controlador.

Nota

Para la mayoría de los casos de uso, el patrón de controlador genérico es suficiente. Use estos controladores especializados cuando necesite enrutamiento avanzado o varios controladores para el mismo tipo de notificación.

Controlador especializado para todas las notificaciones

Registre más controladores que procesen todos los tipos de notificación:

from microsoft_agents_a365.notifications import (
    AgentNotification,
    NotificationTypes
)
from microsoft_agents.activity import ChannelId

# Create notification handler
agent_notification = AgentNotification(app)

# Register handler for all notifications
@agent_notification.on_agent_notification(
    ChannelId(channel="agents", sub_channel="*")
)
async def handle_all_notifications(context, state, notification):
    if notification.notification_type == NotificationTypes.EMAIL_NOTIFICATION:
        if notification.email_notification:
            await context.send_activity(f"Received email: {notification.email_notification.id}")
    elif notification.notification_type == NotificationTypes.WPX_COMMENT:
        if notification.wpx_comment_notification:
            await context.send_activity(f"Received comment: {notification.wpx_comment_notification.comment_id}")

Controlador especializado para notificaciones por correo electrónico

Registre más controladores específicamente para las notificaciones por correo electrónico:

from microsoft_agents_a365.notifications import AgentNotification
from microsoft_agents.activity import ChannelId, AgentSubChannel

# Create notification handler
agent_notification = AgentNotification(app)

# Use the convenience method for email notifications
@agent_notification.on_email()
async def handle_email(context, state, notification):
    email = notification.email_notification
    
    if not email:
        await context.send_activity('No email found')
        return
    
    # Process the email
    email_id = email.id
    conversation_id = email.conversation_id
    
    # Send response
    await context.send_activity('Thank you for your email!')

Controladores especializados para comentarios de documentos

Registre más controladores para las notificaciones de comentarios de Word, Excel y PowerPoint:

from microsoft_agents_a365.notifications import AgentNotification

# Create notification handler
agent_notification = AgentNotification(app)

# Use convenience methods for document notifications
@agent_notification.on_word()
async def handle_word(context, state, notification):
    comment = notification.wpx_comment_notification
    
    if comment:
        document_id = comment.document_id
        comment_id = comment.comment_id
        await context.send_activity(f'Processing Word comment: {comment_id}')

@agent_notification.on_excel()
async def handle_excel(context, state, notification):
    comment = notification.wpx_comment_notification
    
    if comment:
        await context.send_activity('Processing Excel comment')

@agent_notification.on_powerpoint()
async def handle_powerpoint(context, state, notification):
    comment = notification.wpx_comment_notification
    
    if comment:
        await context.send_activity('Processing PowerPoint comment')

Controladores especializados para eventos de ciclo de vida

Registre más controladores para eventos de ciclo de vida del agente, como la creación de identidades de usuario, la incorporación de cargas de trabajo y la eliminación de usuarios:

from microsoft_agents_a365.notifications import AgentNotification

# Create notification handler
agent_notification = AgentNotification(app)

# Handle all lifecycle events
@agent_notification.on_agent_lifecycle_notification("*")
async def handle_lifecycle(context, state, notification):
    lifecycle_notification = notification.agent_lifecycle_notification
    if lifecycle_notification:
        event_type = lifecycle_notification.lifecycle_event_type
        
        if event_type == "agenticUserIdentityCreated":
            await context.send_activity('User identity created')
        elif event_type == "agenticUserWorkloadOnboardingUpdated":
            await context.send_activity('Workload onboarding completed')
        elif event_type == "agenticUserDeleted":
            await context.send_activity('User identity deleted')

Configuración avanzada

En esta sección se tratan las opciones de configuración avanzadas para ajustar los controladores de notificaciones. Mediante estas configuraciones, puede controlar el orden de ejecución del controlador, administrar los requisitos de autenticación y optimizar el procesamiento de notificaciones para escenarios complejos.

Prioridad y clasificación del gestor

Al usar varios controladores especializados, especifique el orden de prioridad mediante valores de clasificación. Los valores de rango más bajos indican una prioridad más alta:

from microsoft_agents_a365.notifications import AgentNotification
from microsoft_agents.activity import ChannelId, AgentSubChannel

# Create notification handler
agent_notification = AgentNotification(app)

# Higher priority handler (processed first)
@agent_notification.on_email(rank=100)
async def high_priority_email(context, state, notification):
    # Handle with high priority
    pass

# Lower priority handler (processed after higher priority)
@agent_notification.on_email(rank=200)
async def low_priority_email(context, state, notification):
    # Handle with lower priority
    pass

Controladores de autenticación

Configura manejadores de inicio de sesión sin intervención para notificaciones que necesitan autenticación:

from microsoft_agents_a365.notifications import AgentNotification
from microsoft_agents.activity import ChannelId, AgentSubChannel

# Create notification handler
agent_notification = AgentNotification(app)

# Handler with automatic authentication
@agent_notification.on_email(auto_sign_in_handlers=['agentic'])
async def authenticated_email(context, state, notification):
    # Authentication is handled automatically
    pass

Código de ejemplo

Para obtener ejemplos completos de control de notificaciones en todos los marcos admitidos, consulte ejemplos del Agente 365.

Prueba tu agente con notificaciones

Después de implementar controladores de notificaciones, pruebe el agente para asegurarse de que recibe y procesa correctamente diferentes tipos de notificación. Siga la guía de pruebas para configurar el entorno y, a continuación, céntrese principalmente en la sección Prueba con actividades de notificación para validar las notificaciones mediante la autenticación agente.

Supervisión del control de notificaciones

Agregue funcionalidades de observabilidad para supervisar el control de notificaciones del agente. Realice un seguimiento del procesamiento de notificaciones, los tiempos de respuesta y las tasas de error para comprender el rendimiento del agente. Infórmate más sobre cómo implementar el rastreo y el seguimiento.

  • Last updated on