Memahami Protokol Kegiatan

Protokol Aktivitas adalah protokol komunikasi standard digunakan di seluruh Microsoft di banyak SDK, layanan, dan klien Microsoft. Protokol Aktivitas digunakan oleh Microsoft 365 Copilot, Microsoft Copilot Studio, dan Agen SDK Microsoft 365. Protokol Aktivitas menentukan struktur 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 dengan klien apa pun yang sedang Anda kerjakan, termasuk klien Microsoft dan non-Microsoft, sehingga Anda tidak perlu membuat logika kustom untuk setiap saluran.

Apa itu Aktivitas?

Sebuah Activity adalah objek JSON terstruktur yang mewakili interaksi apa pun antara pengguna dan agen Anda. Aktivitas tidak terbatas pada pesan berbasis teks. Mereka dapat menyertakan berbagai jenis interaksi, seperti peristiwa seperti pengguna yang bergabung atau berangkat ke klien yang mendukung beberapa pengguna, indikator pengetikan, unggahan file, tindakan kartu, dan peristiwa kustom yang dirancang 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:

Property	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

Untuk menyelesaikan tindakan dari TurnContext objek, pengembang perlu mengakses data dalam aktivitas.

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

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Note

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 dalam Agen SDK Microsoft 365. Ini menyediakan akses ke aktivitas masuk, metode untuk mengirim respons, manajemen status percakapan, dan konteks yang diperlukan untuk menangani satu giliran percakapan. Gunakan untuk mempertahankan konteks, mengirim respons yang sesuai, dan berinteraksi dengan pengguna Anda di klien atau saluran mereka secara efektif. Setiap kali agen Anda menerima aktivitas baru dari sebuah saluran, SDK Agen membuat sebuah instans baru TurnContext dan meneruskannya ke penangan atau metode yang sudah terdaftar. Objek konteks ini ada selama satu giliran dan kemudian dibuang setelah giliran berakhir.

Putaran didefinisikan sebagai perjalanan pulang pergi dari pesan yang dikirim oleh klien dan kemudian mencapai kode Anda. Kode Anda menangani data tersebut dan dapat secara opsional mengirim respons kembali untuk menyelesaikan giliran. Perjalanan pulang pergi tersebut dapat dipecah menjadi langkah-langkah berikut:

Aktivitas masuk: Pengguna mengirim pesan atau melakukan tindakan yang membuat aktivitas.
Kode Anda menerima aktivitas dan agen memprosesnya menggunakan TurnContext.
Agen Anda mengirim satu atau beberapa aktivitas kembali.
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 mendefinisikan apa yang diperlukan atau diharapkan aktivitas lainnya antara klien, pengguna, dan agen.

Ini termasuk:

Pesan
PembaruanPercakapan
Acara
Invoke
Typing

Pesan

Tipe aktivitas yang umum adalah tipe pesan dari Activity. Jenis ini Activity dapat menyertakan teks, lampiran, dan tindakan yang disarankan.

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 pemberitahuan ini, tetapi Microsoft Teams melakukannya.

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.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Events

Jenis EventActivity adalah event kustom yang digunakan oleh saluran atau klien untuk mengirim data terstruktur ke agen Anda. Data ini tidak ditentukan sebelumnya dalam Activity struktur payload.

Anda perlu membuat metode atau handler rute untuk jenis tertentu Event . Kemudian, kelola logika yang diinginkan berdasarkan:

Nama: Nama peristiwa atau pengidentifikasi dari klien
Nilai: 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

Tipe InvokeActivity merupakan tipe aktivitas spesifik yang diminta oleh klien kepada agen untuk mengeksekusi perintah atau operasi. Ini bukan sekadar pesan. Contoh jenis aktivitas ini umum di Microsoft Teams untuk task/fetch dan task/submit. Tidak semua saluran mendukung jenis aktivitas ini.

Typing

Jenis MengetikActivity adalah klasifikasi aktivitas untuk menunjukkan seseorang sedang mengetik dalam percakapan. Aktivitas ini biasanya terlihat antara percakapan manusia ke manusia di klien Microsoft Teams, misalnya. Aktivitas pengetikan tidak didukung di setiap klien. 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 sering bekerja dengan lampiran yang dikirimkan pengguna (atau bahkan agen lain). Klien mengirim Message aktivitas yang menyertakan lampiran (ini bukan jenis aktivitas tertentu). Kode Anda perlu menangani penerimaan pesan dengan lampiran, membaca metadata, dan mengambil file dengan aman dari URL yang disediakan klien. Biasanya, Anda memindahkan file ke penyimpanan Anda sendiri.

Untuk menerima lampiran

Kode berikut menunjukkan cara menerima lampiran.

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 untuk lampiran, klien mengirim permintaan terautentikasi GET untuk mengambil konten aktual. Setiap adaptor memiliki caranya sendiri untuk mendapatkan data tersebut. Misalnya, Teams, OneDrive, dan sebagainya. Penting juga untuk mengetahui bahwa URL tersebut biasanya berumur pendek, jadi jangan asumsikan URL tetap valid untuk waktu yang lama. Batasan inilah sebabnya mengapa pindah ke penyimpanan Anda sendiri penting jika Anda perlu merujuk ke konten nanti.

Kutipan

Penting untuk diketahui bahwa Lampiran dan Kutipan bukan jenis objek yang sama. Klien, seperti Microsoft Teams, menangani kutipan dengan cara mereka sendiri. Mereka menggunakan properti Entitas dari Activity. Anda dapat menambahkan kutipan dengan activity.Entities.Add dan menambahkan objek baru Entity yang memiliki definisi khusus Citation berdasarkan klien Anda. Ini 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

Agen SDK Microsoft 365 dibangun sebagai 'Hub' yang digunakan pengembang untuk membuat agen yang dapat bekerja dengan klien any, termasuk klien yang kami dukung. Ini menyediakan alat bagi pengembang untuk membangun adaptor saluran mereka sendiri menggunakan kerangka kerja yang sama. Arsitektur ini memberikan pengembang keleluasaan dalam hal agen, dan menyediakan ekstensibilitas kepada klien untuk terhubung ke hub tersebut, yang dapat berupa satu atau lebih klien seperti Microsoft Teams, Slack, dan lain-lain.

Saluran yang berbeda memiliki kemampuan dan batasan yang berbeda.

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

Saluran menyertakan data tertentu yang tidak sesuai dengan payload generik Activity di semua saluran. Anda dapat mengakses data ini dari TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) properti dengan mentransmisikannya ke variabel untuk digunakan dalam kode Anda.

Bagian berikut ini meringkas pertimbangan saat bekerja dengan klien umum.

Microsoft Teams

Mendukung Kartu Adaptif yang kaya dengan fitur tingkat lanjut.
Mendukung pembaruan dan penghapusan pesan.
Mengandung data kanal khusus untuk fitur Teams, seperti sebutan dan info rapat.
Mendukung aktivitas pemanggilan 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 dan kartu adaptif.

Web Chat/DirectLine

Web Chat adalah protokol HTTP yang dapat digunakan agen untuk berkomunikasi melalui HTTPS.

Dukungan penuh untuk semua jenis aktivitas.
Mendukung data saluran kustom.

Saluran non-Microsoft

Saluran 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.

Langkah berikutnya

Pelajari tentang AgentApplication

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-29