Compartir a través de


Notificar a agentes

Importante

Debe formar parte del programa de versión preliminar de 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.

El módulo Notificaciones permite a los desarrolladores crear agentes que puedan responder a eventos y notificaciones de aplicaciones de Microsoft 365. Con la compatibilidad con las notificaciones, los agentes pueden recibir y procesar alertas cuando los usuarios interactúan con ellos a través del correo electrónico, los comentarios de documentos u otros escenarios de colaboración.

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
    • Importar tipos de actividad e identificadores de canal
  3. Registro de controladores de notificaciones

    • Uso de métodos de controlador de notificaciones para registrar rutas
    • Configurar controladores para tipos de notificación específicos (por ejemplo: correo electrónico, Word, Excel, PowerPoint)
  4. Procesamiento de notificaciones en el código del agente

    • El agente recibe notificaciones de aplicaciones de Microsoft 365
    • Controlar las notificaciones entrantes y responder correctamente

Tipos de notificación

El SDK de Agents 365 admite los siguientes tipos de notificación:

Tipo de notificación Descripción Identificador de sub canal
Correo electrónico El agente recibe un correo electrónico en el que se mencionan o se abordan 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
Incorporación de cargas de trabajo actualizadas 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

Estos eventos permiten a los agentes realizar tareas de inicialización, operaciones de cleanup o administración de estado en respuesta a los cambios en el ciclo de vida del usuario.

Agregar notificaciones al 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 las actividades de enrutamiento, la administración del estado y el procesamiento de solicitudes
  • AgentNotification: clase para registrar controladores de notificaciones con métodos de decorador. Proporciona on_agent_notification(), on_email(), on_word() y otros decoradores de conveniencia
  • AgentNotificationActivity: contenedor que contiene datos de notificación analizados con propiedades tipificadas como email_notification y wpx_comment_notification que contienen metadatos específicos de notificación (identificadores, detalles de conversación, referencias de documento)
  • NotificationTypes: enumeración de tipos de notificación admitidos (EMAIL_NOTIFICATION, WPX_COMMENT, AGENT_LIFECYCLE)
  • ChannelId: se usa para especificar canales de notificación (por ejemplo, ChannelId(channel="agents", sub_channel="*"))
  • Autorización: contexto de autorización para procesar notificaciones
  • TurnContext: contexto de turno de conversación actual del SDK de agentes

Registro de controladores de notificaciones en el 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

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. Estos métodos le permiten:

  • Registro de varios controladores para el mismo tipo de notificación
  • Establecimiento de la prioridad del controlador con clasificación
  • Configuración de la autenticación automática por 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. Estas configuraciones permiten 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 controlador

Al usar varios controladores especializados, puede especificar 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

Configure controladores de inicio de sesión automático para las notificaciones que requieren 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

Pruebas y supervisión

Prueba del 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

Supervise el control de notificaciones del agente mediante la adición de funcionalidades de observabilidad. Realice un seguimiento del procesamiento de notificaciones, los tiempos de respuesta y las tasas de error para comprender el rendimiento del agente. Más información acerca de la implementación del seguimiento y la supervisión