알림 에이전트

알림 모듈을 사용하면 Microsoft 365 애플리케이션의 이벤트와 알림에 응답하는 에이전트를 만들 수 있습니다. 알림 기능을 사용하면 에이전트가 이메일, 문서 댓글 또는 기타 협업 시나리오에서 사용자가 상호작용할 때 알림을 수신하고 처리할 수 있습니다.

알림 워크플로

AI 에이전트 애플리케이션에서 알림을 활성화하려면 다음 워크플로를 따르세요.

  1. 알림 패키지 설치.

  2. 알림 구성 요소 가져오기

    • 알림 클래스 및 처리기 가져오기.
    • 활동 유형과 채널 식별자를 가져오기.

  3. 알림 처리기 등록

    • 알림 처리기 메서드를 사용하여 경로를 등록하세요.
    • 이메일, Word, Excel, PowerPoint 등 특정 알림 유형에 맞는 처리기를 설정하세요.

  4. 에이전트 코드에서 알림 처리

    • 에이전트는 Microsoft 365 애플리케이션으로부터 알림을 받습니다.
    • 들어오는 알림을 처리하고 적절하게 대응합니다.

알림 유형

Agent 365 SDK는 다음과 같은 알림 유형을 지원합니다.

알림 유형 설명 하위 채널 ID
Email 에이전트가 언급되거나 수신자로 지정된 이메일을 받습니다 email
단어 에이전트가 Word 문서의 댓글에 언급됩니다 word
Excel 에이전트가 Excel 문서의 댓글에 언급됩니다 excel
PowerPoint 에이전트가 PowerPoint 문서의 댓글에 언급됩니다 powerpoint
수명 주기 이벤트 에이전트 수명 주기 알림(사용자 ID 생성, 워크로드 온보딩 및 사용자 삭제) N/A

에이전트 수명 주기 이벤트

에이전트 수명 주기 이벤트를 통해 에이전트가 사용자 ID 관리와 관련된 특정 시스템 이벤트에 응답할 수 있습니다. SDK는 현재 세 가지 수명 주기 이벤트를 지원합니다.

이벤트 유형 이벤트 ID 설명
사용자 ID 생성 agenticUserIdentityCreated 에이전트 사용자 신원이 생성될 때 트리거됩니다
워크로드 온보딩 업데이트 agenticUserWorkloadOnboardingUpdated 에이전트 사용자의 워크로드 온보딩 상태가 업데이트될 때 트리거됩니다
사용자 삭제됨 agenticUserDeleted 에이전트 사용자 ID가 삭제될 때 트리거됩니다

이러한 이벤트를 활용하여 에이전트는 사용자 수명 주기 변경에 대응해 초기화 작업, 정리 작업 또는 상태 관리를 수행할 수 있습니다.

알림 페이로드 참조

에이전트가 알림을 수신하면, 페이로드에는 해당 알림 유형에 특화된 구조화된 데이터가 포함되어 있습니다. 이러한 페이로드를 이해하면 알림을 효과적으로 처리하는 데 필요한 정보를 추출할 수 있습니다.

이메일 알림 페이로드

사용자가 에이전트에게 이메일을 보내거나 이메일에서 에이전트를 언급하면, 에이전트는 다음과 같은 구조의 이메일 알림을 받습니다.

{
  "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>"
    }
  ]
}

문서 댓글 알림 페이로드(Word, Excel, PowerPoint)

사용자가 Word, Excel 또는 PowerPoint 문서의 댓글에서 에이전트를 언급하면, 에이전트는 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"
    }
  ]
}

에이전트에 알림 추가

기존 에이전트에서 알림 처리를 활성화하려면 다음 단계를 따르세요.

알림 구성 요소 가져오기

다음 import 문을 에이전트 파일에 추가하세요.

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: Agent365 애플리케이션을 개발하기 위한 기본 클래스입니다. 활동 라우팅, 상태 관리, 요청 처리 등 핵심 기능을 제공합니다.
  • AgentNotification: 데코레이터 메서드로 알림 처리기를 등록하는 클래스입니다. on_agent_notification(), on_email(), on_word() 및 기타 편의 데코레이터를 제공합니다.
  • AgentNotificationActivity: ID, 대화 세부 정보, 문서 참조 등 알림별 메타데이터를 포함하는 email_notification 및 wpx_comment_notification과 같은 유형화된 속성을 지닌, 구문 분석된 알림 데이터를 담고 있는 래퍼입니다.
  • NotificationTypes: 지원되는 알림 유형을 나열하는 열거형으로, 예를 들어 EMAIL_NOTIFICATION, WPX_COMMENT 등이 있습니다.
  • ChannelId: 알림 채널을 지정할 때 사용합니다(예: ChannelId(channel="agents", sub_channel="*")).
  • 권한 부여: 알림 처리를 위한 권한 부여 컨텍스트.
  • TurnContext: 에이전트 SDK에서 현재 대화의 맥락을 나타내는 컨텍스트.

에이전트에 알림 처리기 등록

에이전트 초기화에 알림 처리기를 추가하세요.

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.')

특정 알림 처리기 구현

각 알림 유형별로 처리기 메서드 추가:

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

보낸 사람 식별

모든 알림 활동에는 Activity.From이 포함됩니다. A365 플랫폼은 이 속성에 발신자의 기본 신원을 자동으로 설정하므로, 별도의 API 호출이나 토큰 획득이 필요하지 않습니다. 모든 알림 처리기 내부에서 이에 접근할 수 있습니다.

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는 ChannelAccount 클래스 인스턴스이며 다음과 같은 속성을 가지고 있습니다.

속성 Description
name 표시 이름
id 채널 사용자 ID
aad_object_id Entra 개체 ID

중요

디스플레이 이름은 사용자가 지정하는 텍스트입니다. LLM 시스템 프롬프트에 주입하기 전에 제어 문자를 제거하고 최대 길이를 강제하여 정제한 후, 프롬프트 인젝션 공격을 방지하세요.

팁

aadObjectId를 Microsoft Graph API와 함께 사용하여 에이전트가 적절한 권한이 있을 때 확장 프로필 데이터(직함, 관리자, 부서)를 조회하세요.

특수 알림 처리기

기본 알림 라우팅을 설정한 후, 더 세밀한 제어를 위해 특화된 처리기 메서드를 사용하세요. 이러한 방법을 사용하면 다음과 같은 작업을 할 수 있습니다.

  • 동일한 알림 유형에 대해 여러 처리기를 등록할 수 있습니다.
  • 순위를 사용하여 처리기 우선순위를 설정할 수 있습니다.
  • 각 처리기에 자동 인증을 설정할 수 있습니다.

참고

대부분의 사용 사례에서는 일반 처리기 패턴만으로도 충분합니다. 고급 라우팅이나 동일한 알림 유형에 대해 여러 처리기가 필요할 때 이러한 특화된 처리기를 사용하세요.

모든 알림 유형을 위한 특화된 처리기

모든 알림 유형을 처리하는 처리기를 추가로 등록하세요.

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

이메일 알림 특화 처리기

이메일 알림을 위한 처리기를 추가로 등록하세요.

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!')

문서 주석을 위한 특수 처리기

Word, Excel 및 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')

수명 주기 이벤트 전용 처리기

에이전트 수명 주기 이벤트(예: 사용자 ID 생성, 워크로드 온보딩 및 사용자 삭제)에 대한 추가 처리기를 등록합니다.

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')

고급 구성

이 섹션에서는 알림 처리기를 세밀하게 조정할 수 있는 고급 설정 옵션에 대해 다룹니다. 이러한 설정을 사용하면 처리기 실행 순서를 제어하고, 인증 요구사항을 관리하며, 복잡한 시나리오에 맞게 알림 처리를 최적화할 수 있습니다.

처리기 우선순위 및 순위

여러 특수 처리기를 사용할 때는 순위 값을 사용해 우선순위를 설정합니다. 순위 값이 낮을수록 우선 순위가 높아집니다.

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

인증 핸들러

인증이 필요한 알림에 대해 자동 로그인 처리기를 설정하세요.

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

샘플 코드

모든 지원되는 프레임워크에서 알림 처리의 전체 실행 예제를 보려면 Agent 365 샘플을 참조하세요.

알림으로 에이전트 테스트하기

알림 처리기를 구현한 후, 에이전트가 다양한 알림 유형을 올바르게 수신하고 처리하는지 테스트하세요. 테스트 가이드를 따라 환경을 구성하고, 알림 활동 테스트 섹션을 중심으로 에이전틱 인증을 사용해 알림을 검증하세요.

알림 처리 모니터링

에이전트의 알림 처리 모니터링을 위한 가시성 기능을 추가하세요. 알림 처리, 응답 시간, 오류율을 추적하여 에이전트 성능을 이해하세요. 추적 및 모니터링 구현 방법에 대해 자세히 알아보세요.

  • Last updated on