Bagikan melalui

Memahami Protokol Aktivitas

Protokol Aktivitas adalah protokol komunikasi dan protokol standar yang digunakan di Microsoft di banyak SDK, layanan, dan klien Microsoft. Ini termasuk Microsoft 365 Copilot, Microsoft Copilot Studio, dan Microsoft 365 Agents SDK. Protokol Aktivitas menentukan bentuk Activity dan bagaimana pesan, peristiwa, dan interaksi mengalir dari saluran, ke kode Anda dan di mana pun di antaranya. Agen dapat terhubung ke satu atau beberapa saluran untuk berinteraksi dengan pengguna dan bekerja dengan agen lain. Protokol Aktivitas menstandarkan protokol komunikasi antara klien mana pun yang sedang Anda kerjakan, termasuk Microsoft dan klien pihak ketiga, sehingga Anda tidak perlu membuat logika kustom per saluran yang sedang Anda kerjakan.

Apa itu Aktivitas?

Sebuah Activity adalah objek JSON terstruktur yang mewakili interaksi apa pun antara pengguna dan agen Anda. Aktivitas bukan hanya pesan berbasis teks, aktivitas dapat mencakup berbagai jenis interaksi termasuk peristiwa seperti pengguna yang bergabung atau keluar untuk klien yang mendukung banyak pengguna, indikator pengetikan, unggahan file, tindakan kartu, dan peristiwa kustom yang dirancang oleh pengembang.

Setiap aktivitas mencakup metadata tentang:

  • Siapa yang mengirimkannya (dari)
  • Siapa yang harus menerimanya (penerima)
  • Konteks percakapan
  • Saluran asalnya
  • Jenis interaksi
  • Data payload

Skema aktivitas - properti kunci

Spesifikasi ini mendefinisikan protokol Aktivitas: Protokol aktivitas - Aktivitas. Beberapa properti kunci yang ditentukan dalam protokol Aktivitas adalah:

Harta benda Description
Id Biasanya dihasilkan oleh saluran jika berasal dari saluran
Type Jenis mengontrol arti aktivitas, misalnya jenis pesan
ChannelID Referensi ChannelID adalah saluran asal dari aktivitas tersebut. Misalnya: msteams.
From Pengirim aktivitas (yang dapat menjadi pengguna atau agen)
Recipient Penerima aktivitas yang dimaksudkan
Text Konten teks pesan
Attachment Konten kaya seperti kartu, gambar file

Mengakses Data aktivitas

Pengembang perlu mengakses data dalam aktivitas untuk menyelesaikan tindakan dari TurnContext objek.

Anda dapat menemukan TurnContext kelas di setiap versi bahasa SDK Agen Microsoft 365:

Nota

Cuplikan kode dalam artikel ini menggunakan C#. Sintaksis dan struktur API untuk versi JavaScript dan Python serupa.

TurnContext adalah objek penting yang digunakan dalam setiap giliran percakapan di SDK Agen Microsoft 365. Ini menyediakan akses ke aktivitas masuk, metode untuk mengirim respons, manajemen status percakapan, dan konteks yang diperlukan untuk menangani satu giliran percakapan. Ini digunakan untuk mempertahankan konteks, mengirim respons yang sesuai, dan berinteraksi dengan pengguna Anda di klien/saluran mereka secara efektif. Setiap kali agen Anda menerima aktivitas baru dari saluran, Agents SDK membuat instance baru TurnContext dan menyalurkannya ke handler/metode yang telah Anda daftarkan. Objek konteks ini ada selama satu putaran dan kemudian dihapus setelah putaran berakhir.

Putaran didefinisikan sebagai perjalanan pulang pergi pesan yang dikirim dari klien yang kemudian melakukan perjalanan ke kode Anda, kode Anda memproses data tersebut dan kode dapat memilih untuk mengirim respons kembali untuk menyelesaikan putaran. Perjalanan pulang-pergi itu dapat dipecah menjadi:

  1. Aktivitas Masuk: Pengguna mengirim pesan atau melakukan tindakan yang membuat aktivitas.
  2. Kode Anda menerima aktivitas dan agen memprosesnya menggunakan TurnContext.
  3. Agen Anda mengirim satu atau beberapa aktivitas kembali.
  4. Giliran berakhir dan TurnContext dibuang.

Akses data dari TurnContext, seperti:

var messageText = turnContext.Activity.Text
var channelID = turnContext.Activity.ChannelId

Cuplikan kode ini menunjukkan contoh giliran lengkap:

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

Di dalam TurnContext kelas, informasi kunci yang umum digunakan meliputi:

  • Aktivitas: Cara utama untuk mendapatkan informasi dari Aktivitas
  • Adaptor: Adaptor saluran yang membuat aktivitas
  • TurnState: Status untuk giliran

Tipe aktivitas

Jenis aktivitas penting karena mendefinisikan apa yang diperlukan atau diharapkan di sisa aktivitas antara klien, pengguna, dan agen.

Message

Aktivitas yang umum adalah tipe pesanActivity yang dapat menyertakan teks, lampiran, dan tindakan yang disarankan, untuk menyebutkan beberapa penggunaan umum dari tipe ini.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text'
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

PembaruanPercakapan

Jenis ConversationUpdateActivity memberi tahu agen Anda saat anggota bergabung atau meninggalkan percakapan. Tidak semua klien mendukung ini, klien penting yang melakukannya adalah Microsoft Teams.

Cuplikan kode berikut menyambut anggota baru dalam percakapan:

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Events

Jenis PeristiwaActivity adalah peristiwa kustom yang memungkinkan saluran atau klien mengirimkan data terstruktur ke agen Anda, yang struktur payload-nya tidak ditentukan sebelumnya dalam Activity.

Anda perlu membuat handler metode/rute untuk jenis tertentu Event lalu mengelola logika yang diinginkan berdasarkan:

Nama - Nama peristiwa atau pengidentifikasi dari Nilai klien - Payload peristiwa yang biasanya merupakan objek JSON

agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>)
{
    var eventName = turnContext.Activity.Name
    var eventValue = turnContext.Activity.Value

    // custom event (E.g. a switch on eventName)
}

Invoke

Jenis Invoke dari Activity adalah jenis aktivitas tertentu yang dilakukan klien pada agen untuk melaksanakan perintah atau operasi, dan bukan hanya pesan. Contoh jenis aktivitas ini umum di Microsoft Teams untuk task/fetch dan task/submit. Tidak semua saluran mendukung jenis aktivitas ini.

Typing

Jenis Typing dari Activity adalah klasifikasi aktivitas untuk menunjukkan seseorang sedang mengetik dalam percakapan. Ini biasanya terlihat antara percakapan manusia ke manusia di klien Microsoft Teams misalnya. Aktivitas pengetikan tidak didukung di setiap klien, dan terutama Microsoft 365 Copilot tidak mendukung aktivitas pengetikan.

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken)

Membuat dan mengirim aktivitas

Untuk mengirim respons, 'TurnContext' menyediakan beberapa metode untuk mengirim respons kembali kepada pengguna.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken) // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken) // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken) // send multiple activities in an Activity array
}

Menggunakan lampiran

Agen biasanya bekerja dengan lampiran yang telah dikirimkan oleh pengguna (atau bahkan agen lain). Klien mengirim Message aktivitas yang menyertakan lampiran (bukan jenis aktivitas tertentu) dan kode Anda perlu menangani penerimaan pesan dengan lampiran, membaca metadata, dan mengambil file dengan aman dari URL yang disediakan klien. Biasanya, file tersebut kemudian dipindahkan ke penyimpanan Anda sendiri.

Untuk menerima lampiran

Kode berikut menunjukkan cara menerima dan melampirkan

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count >0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        }
    }
}

Biasanya, untuk menerima dokumen pada lampiran, klien mengirim permintaan terautentikasi GET untuk mengambil konten aktual - setiap adaptor memiliki cara tersendiri untuk mendapatkan data tersebut misalnya, Teams, OneDrive, dan sebagainya. Penting juga untuk mengetahui bahwa url tersebut biasanya berumur pendek, jadi jangan asumsikan mereka akan tinggal di sana, itulah sebabnya pindah ke penyimpanan Anda sendiri penting jika Anda perlu merujuk ke ini nanti.

Kutipan

Penting untuk diketahui bahwa Lampiran danKutipan bukan jenis objek yang sama. Kutipan dapat ditangani oleh klien, seperti Microsoft Teams, dengan cara mereka sendiri. Mereka menggunakan properti Entitas dari Activity dan dapat ditambahkan dengan activity.Entities.Add, serta menambahkan objek Entity baru yang memiliki definisi Citation spesifik berdasarkan klien Anda. Ini akan diserialisasikan sebagai objek JSON yang kemudian dideserialisasi klien berdasarkan bagaimana rendernya di klien. Pada dasarnya, Lampiran adalah pesan, dan Kutipan dapat mereferensikan lampiran dan merupakan objek lain yang dikirim dalam EntitiesActivity payload.

Pertimbangan spesifik saluran

Microsoft 365 Agents SDK dibangun sebagai 'Hub' yang memungkinkan pengembang untuk membuat agen yang dapat bekerja dengan klien apa pun , termasuk klien yang kami dukung dan menyediakan alat bagi pengembang untuk membangun adaptor saluran mereka sendiri menggunakan kerangka kerja yang sama. Ini memberikan banyak pilihan kepada pengembang dalam hal agen, dan menyediakan kemampuan ekstensi kepada klien untuk terhubung ke hub tersebut, yang bisa menjadi satu atau beberapa klien seperti Microsoft Teams, Slack, dan lainnya.

Saluran yang berbeda memiliki kemampuan dan batasan yang berbeda, dan berikut ini adalah ringkasan pertimbangan saat bekerja dengan klien umum.

Anda dapat memeriksa saluran dari mana Anda menerima aktivitas dengan memeriksa properti channelId di Activity.

Saluran mencakup data tertentu yang tidak sesuai dengan payload Activity generik di semua saluran, dan ini dapat diakses dari TurnContext.Activity.ChannelData dan secara khusus mentransmisikannya ke variabel untuk digunakan dalam kode Anda.

Microsoft Teams

  • Mendukung Kartu Adaptif yang kaya dengan fitur canggih
  • Mendukung pembaruan dan penghapusan pesan
  • Memiliki data saluran khusus untuk fitur Teams (sebutan, info rapat, dan sebagainya)
  • Mendukung aktivitas pemanggilan fungsi untuk modul tugas

Microsoft 365 Copilot

  • Terutama berfokus pada aktivitas pesan
  • Mendukung kutipan dan referensi dalam respons
  • Memerlukan respons streaming
  • Dukungan terbatas untuk kartu kaya/kartu adaptif

WebChat/DirectLine

Web Chat adalah protokol HTTP yang digunakan untuk agen untuk berbicara melalui HTTPS

  • Dukungan penuh untuk semua jenis aktivitas
  • Mendukung data saluran khusus

Saluran pihak ketiga

Ini termasuk Slack, Facebook, dan banyak lagi.

  • Mungkin memiliki dukungan terbatas untuk jenis aktivitas tertentu
  • Penyajian kartu mungkin berbeda atau tidak didukung
  • Selalu periksa dokumentasi saluran tertentu
  • Last updated on