Memahami Protokol Aktivitas

Protokol Aktivitas adalah protokol komunikasi standar yang digunakan di seluruh Microsoft pada banyak SDK, layanan, dan klien Microsoft. Protokol Aktivitas digunakan oleh Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams, dan Agen SDK Microsoft 365. Protokol Aktivitas mendefinisikan struktur dari Activity serta bagaimana pesan, peristiwa, dan interaksi mengalir dari sebuah saluran ke kode Anda serta tempat-tempat lain 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 Anda gunakan, 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. Aktivitas dapat mencakup berbagai jenis interaksi, seperti peristiwa seperti pengguna bergabung atau meninggalkan percakapan untuk klien yang mendukung banyak pengguna, indikator sedang mengetik, unggahan file, tindakan kartu, dan peristiwa khusus yang dirancang oleh pengembang.

Setiap aktivitas menyertakan metadata tentang:

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

Skema aktivitas - properti kunci

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

Properti	Deskripsi
`Id`	Biasanya dihasilkan oleh saluran jika berasal dari sebuah saluran
`Type`	Jenis menentukan makna suatu aktivitas, misalnya jenis pesan
`ChannelID`	`ChannelID` merujuk pada saluran tempat aktivitas berasal. Misalnya: `msteams`.
`From`	Pengirim aktivitas (yang dapat berupa pengguna atau agen)
`Recipient`	Penerima aktivitas yang dimaksudkan
`Text`	Konten pesan teks
`Attachment`	Konten kaya seperti kartu, gambar file

Mengakses data aktivitas

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

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

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Catatan

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

TurnContext merupakan objek penting yang digunakan dalam setiap giliran percakapan di Agen SDK Microsoft 365. Objek ini memberikan akses ke aktivitas yang masuk, metode untuk mengirim respons, manajemen status percakapan, dan konteks yang diperlukan untuk menangani satu giliran percakapan. Gunakan objek ini untuk menjaga konteks, memberikan respons yang sesuai, dan berinteraksi dengan pengguna Anda secara efektif di klien atau saluran mereka. Setiap kali agen Anda menerima aktivitas baru dari sebuah saluran, SDK Agen membuat sebuah instans TurnContext baru dan meneruskannya ke handler atau metode yang sudah terdaftar. Objek konteks ini ada selama satu putaran dan kemudian dibuang setelah putaran berakhir.

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

Aktivitas masuk: Pengguna mengirim pesan atau melakukan tindakan yang memicu aktivitas.
Kode Anda menerima aktivitas dan agen memprosesnya menggunakan TurnContext.
Agen Anda mengirim satu atau beberapa aktivitas kembali.
Putaran berakhir dan TurnContext dibuang.

Akses data dari TurnContext, seperti:

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

Cuplikan kode ini menampilkan contoh sebuah putaran yang 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 kelas TurnContext, informasi kunci yang umum digunakan antara lain:

Aktivitas: Cara utama untuk memperoleh informasi dari aktivitas
Adaptor: Adaptor saluran yang membuat aktivitas
TurnState: Status untuk putaran

Tipe aktivitas

Jenis aktivitas menentukan apa yang diperlukan atau diharapkan dari aktivitas antara klien, pengguna, dan agen.

Ini termasuk:

Pesan
ConversationUpdate
Kejadian
Panggil
Mengetik

Pesan

Jenis aktivitas yang umum adalah jenis Pesan dari Activity. Jenis Activity ini dapat mencakup 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);
});

ConversationUpdate

Jenis ConversationUpdate dari Activity memberi tahu agen Anda kapan anggota bergabung atau keluar dari percakapan. Tidak semua klien mendukung pemberitahuan ini, tetapi Microsoft Teams mendukungnya.

Cuplikan kode berikut menyapa 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);
            }
        }
    }
})

Aktivitas

Jenis Peristiwa dari Activity adalah peristiwa khusus yang digunakan oleh saluran atau klien untuk mengirim data terstruktur ke agen Anda. Data ini tidak didefinisikan sebelumnya dalam struktur payload Activity.

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

Nama: Nama atau pengidentifikasi peristiwa dari klien
Nilai: Payload peristiwa yang biasanya berupa 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)
});

Panggil

Jenis Panggil dari Activity jenis aktivitas tertentu yang dipanggil klien dalam agen untuk melaksanakan perintah atau operasi. Ini bukan hanya pesan. Contoh jenis aktivitas tersebut sering ditemukan di Microsoft Teams untuk task/fetch dan task/submit. Tidak semua saluran mendukung tipe aktivitas ini.

Mengetik

Jenis Mengetik dari Activity adalah klasifikasi aktivitas untuk menunjukkan seseorang sedang mengetik dalam percakapan. Aktivitas ini biasanya terlihat dalam percakapan antara manusia ke manusia di klien Microsoft Teams, misalnya. Tidak semua klien mendukung aktivitas pengetikan. Perlu dicatat, 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);

Aktivitas membuat dan mengirim

Untuk mengirim respons, TurnContext menyediakan beberapa metode untuk mengirim respons kembali ke 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 mengirimkan aktivitas Message yang menyertakan lampiran (ini bukan jenis aktivitas tertentu). Kode Anda perlu menangani penerimaan pesan yang disertai lampiran, membaca metadata, serta mengambil file secara aman dari URL yang diberikan oleh klien. Biasanya, Anda memindahkan file ke penyimpanan Anda sendiri.

Untuk menerima lampiran

Kode berikut menampilkan 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 lampiran, klien mengirimkan permintaan GET yang diautentikasi untuk mengambil konten yang sebenarnya. Setiap adapter memiliki caranya sendiri untuk mendapatkan data tersebut. Misalnya, Teams, OneDrive, dan sebagainya. Penting juga untuk diketahui bahwa URL tersebut biasanya berumur pendek, jadi jangan berasumsi bahwa URL tersebut tetap valid untuk waktu yang lama. Batasan inilah mengapa beralih ke penyimpanan Anda sendiri penting jika Anda perlu merujuk ke konten nanti.

Kutipan

Penting untuk diketahui bahwa Lampiran dan Kutipan bukan tipe objek yang sama. Klien, seperti Microsoft Teams, menangani kutipan dengan caranya 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 akan diserialkan sebagai objek JSON yang kemudian dideserialisasi oleh klien berdasarkan cara render di klien. Secara fundamental, Lampiran adalah pesan, dan Kutipan dapat merujuk ke lampiran serta merupakan objek lain yang dikirim dalam Entities dari payload Activity.

Pertimbangan khusus saluran

Agen SDK Microsoft 365 dibangun sebagai 'Hub' yang digunakan pengembang untuk membuat agen yang dapat bekerja dengan klien apa pun, termasuk klien yang kami dukung. Layanan ini menyediakan alat bagi pengembang untuk membangun adapter saluran mereka sendiri menggunakan kerangka kerja yang sama. Arsitektur ini memberikan fleksibilitas kepada pengembang dalam hal agen, dan memungkinkan ekstensibilitas ke klien untuk terhubung ke hub tersebut, yang dapat berupa satu atau beberapa klien seperti Microsoft Teams, Slack, dan lainnya.

Setiap saluran memiliki kemampuan dan keterbatasannya sendiri.

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

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

Bagian berikut merangkum pertimbangan saat bekerja dengan klien umum.

Microsoft Teams

Mendukung Kartu Adaptif yang kaya dengan fitur-fitur canggih.
Mendukung pembaruan dan penghapusan pesan.
Memiliki data saluran khusus untuk fitur Teams seperti sebutan dan info rapat.
Mendukung aktivitas pemanggilan untuk modul tugas.

Microsoft 365 Copilot

Terutama difokuskan 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 khusus.

Saluran non-Microsoft

Saluran ini mencakup Slack, Facebook, dan lainnya.

Mungkin memiliki dukungan terbatas untuk jenis aktivitas tertentu.
Penyajian kartu mungkin berbeda atau bahkan tidak didukung.
Selalu periksa dokumentasi saluran yang spesifik.

Langkah berikutnya

Pelajari tentang AgentApplication

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-31