Memberitahukan agen

Dengan menggunakan modul Notifikasi, Anda dapat membuat agen yang merespons peristiwa dan notifikasi dari aplikasi Microsoft 365. Dengan menggunakan fitur pemberitahuan, agen dapat menerima dan memproses peringatan saat pengguna berinteraksi dengan mereka melalui email, komentar dokumen, atau skenario kolaboratif lainnya.

Alur kerja pemberitahuan

Ikuti alur kerja ini untuk mengaktifkan pemberitahuan pada aplikasi agen AI Anda:

  1. Menginstal Paket pemberitahuan.

  2. Impor komponen pemberitahuan

    • Impor kelas dan handler pemberitahuan.
    • Impor jenis aktivitas dan ID saluran.

  3. Mendaftarkan handler pemberitahuan

    • Gunakan metode handler pemberitahuan untuk mendaftarkan rute.
    • Konfigurasikan handler untuk jenis pemberitahuan tertentu, seperti email, Word, Excel, atau PowerPoint.

  4. Memproses pemberitahuan dalam kode agen

    • Agen menerima pemberitahuan dari aplikasi Microsoft 365.
    • Tangani pemberitahuan yang masuk dan berikan respons yang sesuai.

Jenis Pemberitahuan

SDK Agent 365 mendukung jenis pemberitahuan berikut:

Jenis pemberitahuan Deskripsi ID Sub-Saluran
Email Agen menerima email ketika mereka disebutkan atau ditujukan kepada mereka email
Word Agen disebutkan dalam komentar di dokumen Word word
Excel Agen disebutkan dalam komentar di dokumen Excel excel
PowerPoint Agen disebutkan dalam komentar di dokumen PowerPoint powerpoint
Peristiwa Siklus Hidup Pemberitahuan siklus hidup agen (identitas pengguna dibuat, onboarding beban kerja, pengguna dihapus) Tidak Tersedia

Peristiwa siklus hidup agen

Peristiwa siklus hidup agen memungkinkan agen Anda merespons peristiwa sistem tertentu yang terkait dengan manajemen identitas pengguna agen. SDK saat ini mendukung tiga peristiwa siklus hidup:

Jenis peristiwa ID Peristiwa Deskripsi
Identitas Pengguna Dibuat agenticUserIdentityCreated Dipicu ketika identitas pengguna agen dibuat
Onboarding Beban Kerja Diperbarui agenticUserWorkloadOnboardingUpdated Dipicu ketika status onboarding beban kerja pengguna agen diperbarui
Pengguna Dihapus agenticUserDeleted Dipicu ketika identitas pengguna agen dihapus

Dengan memanfaatkan peristiwa ini, agen dapat melakukan tugas inisialisasi, operasi pembersihan, atau pengelolaan status sebagai respons terhadap perubahan siklus hidup pengguna.

Referensi payload pemberitahuan

Saat agen Anda menerima pemberitahuan, payload berisi data terstruktur yang khusus untuk jenis pemberitahuan. Memahami payload ini membantu Anda mengekstrak informasi yang Anda butuhkan untuk memproses pemberitahuan secara efektif.

Payload pemberitahuan email

Saat pengguna mengirim email ke agen Anda atau menyebut agen Anda dalam email, agen Anda akan menerima pemberitahuan email dengan struktur berikut:

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

Payload pemberitahuan komentar dokumen (Word, Excel, PowerPoint)

Ketika seorang pengguna menyebut agen Anda dalam komentar di dokumen Word, Excel, atau PowerPoint, agen Anda akan menerima pemberitahuan komentar 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"
    }
  ]
}

Menambahkan pemberitahuan ke agen Anda

Ikuti langkah-langkah berikut untuk mengaktifkan penanganan pemberitahuan di agen yang ada:

Impor komponen pemberitahuan

Tambahkan impor ini ke file agen Anda:

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: Kelas dasar untuk membangun aplikasi Agent365. Ini menyediakan fungsionalitas inti untuk perutean aktivitas, mengelola status, dan memproses permintaan.
  • AgentNotification: Kelas untuk mendaftarkan handler pemberitahuan dengan metode dekorator. Ini menyediakan on_agent_notification(), on_email(), on_word(), dan dekorator kenyamanan lainnya.
  • AgentNotificationActivity: Pembungkus yang berisi data pemberitahuan yang telah diurai dengan properti bertipe seperti email_notification and wpx_comment_notification yang berisi metadata khusus pemberitahuan seperti ID, detail percakapan, dan referensi dokumen.
  • NotificationTypes: Enumerasi tipe pemberitahuan yang didukung seperti EMAIL_NOTIFICATION, WPX_COMMENT.
  • ChannelId: Gunakan untuk menentukan saluran pemberitahuan, misalnya, ChannelId(channel="agents", sub_channel="*").
  • Otorisasi: Konteks otorisasi untuk memproses pemberitahuan.
  • TurnContext: Konteks giliran percakapan saat ini dari Agents SDK.

Mendaftarkan handler pemberitahuan kepada agen Anda

Tambahkan handler pemberitahuan ke inisialisasi agen Anda:

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

Mengimplementasikan handler pemberitahuan spesifik

Tambahkan metode handler untuk setiap jenis pemberitahuan:

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

Identifikasi pengirim

Setiap aktivitas pemberitahuan memuat Activity.From. Platform A365 mengisi properti ini dengan identitas dasar pengirim, sehingga Anda tidak perlu melakukan panggilan API atau memperoleh token apa pun. Akseslah dalam handler pemberitahuan apa pun:

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 adalah instans ChannelAccount class yang memiliki properti berikut:

Properti Deskripsi
name Nama tampilan
id ID pengguna saluran
aad_object_id ID Objek Entra

Penting

Nama tampilan adalah teks yang dikendalikan pengguna. Hapus (karakter kontrol strip, dan batasi panjang maksimum) sebelum memasukkannya ke perintah sistem LLM untuk mencegah serangan injeksi perintah.

Kiat

Gunakan aadObjectId dengan Microsoft Graph API untuk mengambil data profil yang diperluas (jabatan, manajer, departemen) saat agen Anda memiliki izin yang sesuai.

Penanganan pemberitahuan khusus

Setelah menyiapkan perutean pemberitahuan dasar, gunakan metode handler khusus untuk kontrol yang lebih mendetail. Menggunakan metode ini, Anda dapat:

  • Mendaftarkan beberapa handler untuk jenis pemberitahuan yang sama.
  • Menetapkan prioritas handler menggunakan peringkat.
  • Mengonfigurasikan autentikasi otomatis untuk setiap handler.

Catatan

Untuk sebagian besar kasus penggunaan, pola handler generik sudah cukup. Gunakan handler khusus ini saat Anda memerlukan perutean tingkat lanjut atau beberapa handler untuk jenis pemberitahuan yang sama.

Handler khusus untuk semua pemberitahuan

Mendaftarkan lebih banyak handler yang memproses semua jenis pemberitahuan:

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

Handler khusus untuk pemberitahuan email

Daftarkan handler khusus tambahan untuk pemberitahuan email:

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

Handler khusus untuk komentar dokumen

Daftarkan lebih banyak handler untuk pemberitahuan komentar Word, Excel, dan 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')

Handler khusus untuk peristiwa siklus hidup

Daftarkan lebih banyak handler untuk peristiwa siklus hidup agen, seperti pembuatan identitas pengguna, onboarding beban kerja, dan penghapusan pengguna:

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

Konfigurasi tingkat lanjut

Bagian ini membahas opsi konfigurasi tingkat lanjut untuk mengatur secara lebih rinci handler pemberitahuan Anda. Dengan menggunakan konfigurasi ini, Anda dapat mengontrol urutan eksekusi handler, mengelola persyaratan autentikasi, dan mengoptimalkan proses pemberitahuan untuk skenario yang kompleks.

Prioritas dan peringkat handler

Saat Anda menggunakan beberapa handler khusus, tentukan urutan prioritas menggunakan nilai peringkat. Nilai peringkat yang lebih rendah menunjukkan prioritas yang lebih tinggi.

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

Handler autentikasi

Konfigurasikan handler masuk otomatis untuk pemberitahuan yang memerlukan autentikasi:

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

Kode Sampel

Untuk contoh lengkap penanganan pemberitahuan di semua kerangka kerja yang didukung, lihat Sampel Agent 365.

Menguji agen Anda dengan pemberitahuan

Setelah mengimplementasikan handler pemberitahuan, uji agen Anda untuk memastikan bahwa agen menerima dan memproses berbagai tipe pemberitahuan dengan benar. Ikuti menguji panduan untuk menyiapkan lingkungan Anda, lalu fokuskan terutama pada bagian Uji dengan aktivitas pemberitahuan untuk memvalidasi pemberitahuan Anda menggunakan autentikasi agenik.

Memantau penanganan pemberitahuan

Tambahkan kemampuan observabilitas untuk memantau penanganan pemberitahuan agen Anda. Lacak pemrosesan pemberitahuan, waktu respons, dan tingkat kesalahan untuk memahami performa agen. Pelajari lebih lanjut cara menerapkan pelacakan dan pemantauan.

  • Last updated on