Dasar-dasar Microsoft Bot Framework

BERLAKU UNTUK: SDK v4

Bot adalah aplikasi yang berinteraksi dengan pengguna dengan cara percakapan, menggunakan teks, grafik (seperti kartu atau gambar), atau ucapan. Azure AI Bot Service adalah platform cloud. Ini menghosting bot dan membuatnya tersedia untuk saluran, seperti Microsoft Teams, Facebook, atau Slack.

Bot Framework Service, yang merupakan komponen dari Azure AI Bot Service, mengirim informasi antara aplikasi yang terhubung dengan bot pengguna dan bot. Setiap saluran dapat menyertakan informasi tambahan dalam aktivitas yang mereka kirim. Sebelum membuat bot, penting untuk memahami bagaimana bot menggunakan objek aktivitas untuk berkomunikasi dengan penggunanya.

Diagram ini mengilustrasikan dua jenis aktivitas, pembaruan dan pesan percakapan, yang mungkin ditukar saat pengguna berkomunikasi dengan bot gema.

Bot Framework Service mengirimkan pembaruan percakapan saat pihak bergabung dalam percakapan. Misalnya, saat memulai percakapan dengan Bot Framework Emulator, Anda mungkin melihat dua aktivitas pembaruan percakapan (satu untuk pengguna yang bergabung dengan percakapan dan satu untuk gabungan bot). Untuk membedakan aktivitas pembaruan percakapan ini, periksa siapa yang disertakan dalam properti tambahan anggota aktivitas.

Aktivitas pesan membawa informasi percakapan antara para pihak. Dalam contoh bot echo, aktivitas pesan membawa teks sederhana dan saluran akan merender teks ini. Atau, aktivitas pesan mungkin membawa teks untuk diucapkan, tindakan atau kartu yang disarankan untuk ditampilkan.

Tip

Terserah setiap saluran untuk menerapkan protokol Bot Framework, dan bagaimana setiap saluran melakukannya mungkin sedikit berbeda. Misalnya, beberapa saluran mengirim aktivitas pembaruan percakapan terlebih dahulu, dan beberapa mengirim aktivitas pembaruan percakapan setelah mereka mengirim aktivitas pesan pertama. Saluran mungkin menyertakan bot dan pengguna dalam satu aktivitas pembaruan percakapan, sementara yang lain mungkin mengirim dua aktivitas pembaruan percakapan.

Dalam contoh ini, bot membuat dan mengirim aktivitas pesan sebagai respons terhadap aktivitas pesan masuk yang diterimanya. Namun, bot dapat merespons dengan cara lain untuk aktivitas pesan yang diterima, dan biasanya bot merespons aktivitas pembaruan percakapan dengan mengirim aktivitas pesan dengan pesan selamat datang. Untuk informasi selengkapnya, lihat cara menyambut pengguna.

The Bot Framework SDK

Bot Framework SDK memungkinkan Anda membuat bot yang dapat dihosting di Azure AI Bot Service. Layanan ini menentukan REST API dan protokol aktivitas tentang bagaimana bot dan saluran atau pengguna Anda dapat berinteraksi. SDK dibangun di atas REST API ini dan menyediakan abstraksi layanan sehingga Anda dapat fokus pada logika percakapan. Meskipun Anda tidak perlu memahami layanan REST untuk menggunakan SDK, memahami beberapa fiturnya dapat membantu.

Bot adalah aplikasi yang memiliki antarmuka percakapan. Mereka dapat digunakan untuk menggeser tugas sederhana dan berulang, seperti mengambil reservasi makan malam atau mengumpulkan informasi profil, ke sistem otomatis yang mungkin tidak lagi memerlukan intervensi manusia langsung. Pengguna berkomunikasi dengan bot menggunakan teks, kartu interaktif, dan ucapan. Interaksi bot dapat menjadi pertanyaan dan jawaban cepat, atau dapat menjadi percakapan canggih yang menyediakan akses ke layanan secara cerdas.

Catatan

Dukungan untuk fitur yang disediakan oleh SDK dan REST API bervariasi menurut saluran. Anda dapat menguji bot menggunakan Bot Framework Emulator, tetapi Anda juga harus menguji semua fitur bot di setiap saluran tempat Anda ingin membuat bot tersedia.

Interaksi melibatkan pertukaran aktivitas, yang ditangani secara bergiliran.

Aktivitas

Setiap interaksi antara pengguna (atau saluran) dan bot diwakili sebagai aktivitas. Skema Aktivitas Kerangka Kerja Bot menentukan aktivitas yang dapat ditukar antara pengguna atau saluran dan bot. Aktivitas dapat mewakili teks atau ucapan manusia, pemberitahuan aplikasi ke aplikasi, reaksi terhadap pesan lain, dan sebagainya.

Berubah

Dalam percakapan, orang sering berbicara satu per satu, bergantian berbicara. Dengan bot, umumnya bereaksi terhadap input pengguna. Dalam Bot Framework SDK, giliran terdiri dari aktivitas masuk pengguna ke bot dan aktivitas apa pun yang dikirim bot kembali kepada pengguna sebagai respons langsung. Anda dapat menganggap giliran sebagai pemrosesan yang terkait dengan bot yang menerima aktivitas tertentu.

Misalnya, pengguna mungkin meminta bot untuk melakukan tugas tertentu. Bot mungkin merespons dengan pertanyaan untuk mendapatkan informasi selengkapnya tentang tugas, di mana giliran ini berakhir. Pada giliran berikutnya, bot menerima pesan baru dari pengguna yang mungkin berisi jawaban atas pertanyaan bot, atau mungkin mewakili perubahan subjek atau permintaan untuk mengabaikan permintaan awal untuk melakukan tugas.

Struktur aplikasi bot

SDK mendefinisikan kelas bot yang menangani penalaran percakapan untuk aplikasi bot. Kelas bot:

• Mengenali dan menginterpretasikan input pengguna.
• Alasan tentang input dan melakukan tugas yang relevan.
• Menghasilkan respons tentang apa yang dilakukan atau telah dilakukan bot.

SDK juga mendefinisikan kelas adaptor yang menangani konektivitas dengan saluran. Adaptor:

• Menyediakan metode untuk menangani permintaan dari dan metode untuk menghasilkan permintaan ke saluran pengguna.
• Termasuk alur middleware, yang mencakup pemrosesan giliran di luar handler giliran bot Anda.
• Memanggil handler giliran bot dan menangkap kesalahan yang tidak ditangani di handler giliran.

Selain itu, bot sering kali perlu mengambil dan menyimpan status setiap giliran. Status ditangani melalui kelas penyimpanan, status bot, dan pengakses properti. SDK tidak menyediakan penyimpanan bawaan, tetapi menyediakan abstraksi untuk penyimpanan dan beberapa implementasi lapisan penyimpanan. Topik status pengelolaan menjelaskan fitur status dan penyimpanan ini.

SDK tidak mengharuskan Anda menggunakan lapisan aplikasi tertentu untuk mengirim dan menerima permintaan web. Kerangka Kerja Bot memiliki templat dan sampel untuk ASP.NET (C#), pulihkan (JavaScript), dan aiohttp (Python). Namun, Anda dapat memilih untuk menggunakan lapisan aplikasi yang berbeda untuk aplikasi Anda.

Saat Anda membuat bot menggunakan SDK, Anda menyediakan kode untuk menerima lalu lintas HTTP dan meneruskannya ke adaptor. Kerangka Kerja Bot menyediakan beberapa templat dan sampel yang dapat Anda gunakan untuk mengembangkan bot Anda sendiri.

Catatan

Bot Framework JavaScript, C#, dan Python SDK akan terus didukung, namun, Java SDK dihentikan dengan dukungan jangka panjang akhir yang berakhir pada November 2023.

Bot yang ada yang dibangun dengan Java SDK akan terus berfungsi.

Untuk pembuatan bot baru, pertimbangkan untuk menggunakan Microsoft Copilot Studio dan baca tentang memilih solusi salinan yang tepat.

Untuk informasi selengkapnya, lihat Masa depan pembuatan bot.

Logika bot

Objek bot berisi penalaran percakapan atau logika untuk giliran dan mengekspos handler giliran, yang merupakan metode yang dapat menerima aktivitas masuk dari adaptor bot.

SDK menyediakan beberapa paradigma yang berbeda untuk mengelola logika bot Anda.

• Penanganan aktivitas menyediakan model berbasis peristiwa di mana jenis aktivitas dan subjenis yang masuk adalah peristiwa. Pertimbangkan penanganan aktivitas untuk bot yang memiliki interaksi singkat yang terbatas dengan pengguna.
  • Gunakan handler aktivitas dan terapkan handler untuk setiap jenis aktivitas atau subtipe yang akan dikenali dan direksi bot Anda.
  • Gunakan penanganan aktivitas Teams untuk membuat bot yang dapat tersambung ke saluran Teams. (Saluran Teams mengharuskan bot untuk menangani beberapa perilaku khusus saluran.)
• Pustaka dialog menyediakan model berbasis status untuk mengelola percakapan yang berjalan lama dengan pengguna.
  • Gunakan handler aktivitas dan dialog komponen untuk percakapan yang sebagian besar berurutan. Untuk informasi selengkapnya, lihat tentang dialog komponen dan air terjun.
• Terapkan kelas bot Anda sendiri dan berikan logika Anda sendiri untuk menangani setiap giliran. Misalnya, lihat cara membuat permintaan Anda sendiri untuk mengumpulkan input pengguna.

Adaptor bot

Adaptor memiliki metode aktivitas proses untuk memulai giliran.

• Dibutuhkan isi permintaan (payload permintaan, diterjemahkan ke aktivitas) dan header permintaan sebagai argumen.
• Ini memeriksa apakah header autentikasi valid.
• Ini membuat objek konteks untuk giliran. Objek konteks mencakup informasi tentang aktivitas.
• Ini mengirim objek konteks melalui alur middleware-nya.
• Kemudian mengirimkan objek konteks ke handler giliran objek bot.

Adaptor juga:

• Memformat dan mengirim aktivitas respons. Respons ini biasanya merupakan pesan untuk pengguna, tetapi juga dapat menyertakan informasi yang akan digunakan oleh saluran pengguna secara langsung.
• Menampilkan metode lain yang disediakan oleh BOT Connector REST API, seperti memperbarui pesan dan menghapus pesan.
• Menangkap kesalahan atau pengecualian yang tidak ditangkap untuk giliran tersebut.

Konteks giliran

Objek konteks giliran menyediakan informasi tentang aktivitas seperti pengirim dan penerima, saluran, dan data lain yang diperlukan untuk memproses aktivitas. Ini juga memungkinkan penambahan informasi selama giliran di berbagai lapisan bot.

Konteks giliran adalah salah satu abstraksi terpenting dalam SDK. Tidak hanya membawa aktivitas masuk ke semua komponen middleware dan logika aplikasi tetapi juga menyediakan mekanisme di mana komponen middleware dan logika bot dapat mengirim aktivitas keluar.

Middleware

Middleware sama seperti middleware olahpesan lainnya, yang terdiri dari serangkaian komponen linier yang masing-masing dijalankan secara berurutan, memberikan setiap kesempatan untuk beroperasi pada aktivitas. Tahap akhir alur middleware adalah panggilan balik ke handler giliran pada kelas bot yang telah didaftarkan aplikasi dengan metode aktivitas proses adaptor. Middleware mengimplementasikan metode on turn yang dipanggil adaptor.

Handler giliran mengambil konteks giliran sebagai argumennya, biasanya logika aplikasi yang berjalan di dalam fungsi handler giliran akan memproses konten aktivitas masuk dan menghasilkan satu atau beberapa aktivitas sebagai respons, mengirim aktivitas keluar ini menggunakan fungsi aktivitas kirim pada konteks giliran. Aktivitas pengiriman panggilan pada konteks giliran akan menyebabkan komponen middleware dipanggil pada aktivitas keluar. Komponen middleware dijalankan sebelum dan sesudah fungsi handler giliran bot. Eksekusi secara inheren bersarang dan, dengan demikian, kadang-kadang disebut seperti bawang.

Topik middleware menjelaskan middleware secara lebih mendalam.

Status bot dan penyimpanan

Seperti halnya aplikasi web lainnya, bot secara inheren tanpa status. Status dalam bot mengikuti paradigma yang sama dengan aplikasi web modern, dan Bot Framework SDK menyediakan lapisan penyimpanan dan abstraksi manajemen status untuk mempermudah manajemen status.

Topik status pengelolaan menjelaskan fitur status dan penyimpanan ini.

Titik akhir olahpesan dan provisi

Biasanya, aplikasi Anda akan memerlukan titik akhir REST untuk menerima pesan. Ini juga perlu menyediakan sumber daya untuk bot Anda sesuai dengan platform yang Anda putuskan untuk digunakan.

Ikuti mulai cepat Buat bot untuk membuat dan menguji bot gema sederhana.

Detail HTTP

Aktivitas tiba di bot dari Bot Framework Service melalui permintaan HTTP POST. Bot merespons permintaan POST masuk dengan kode status HTTP 200. Aktivitas yang dikirim dari bot ke saluran dikirim pada HTTP POST terpisah ke Bot Framework Service. Ini, pada gilirannya, diakui dengan kode status HTTP 200.

Protokol tidak menentukan urutan permintaan POST ini dan pengakuannya dibuat. Namun, agar sesuai dengan kerangka kerja layanan HTTP umum, biasanya permintaan ini ditumpuk, yang berarti bahwa permintaan HTTP keluar dibuat dari bot dalam cakupan permintaan HTTP masuk. Pola ini diilustrasikan dalam diagram sebelumnya. Karena ada dua koneksi HTTP yang berbeda kembali ke belakang, model keamanan harus menyediakan keduanya.

Catatan

Bot memiliki 15 detik untuk mengakui panggilan dengan status 200 di sebagian besar saluran. Jika bot tidak merespons dalam waktu 15 detik, kesalahan HTTP GatewayTimeout (504) terjadi.

Tumpukan pemrosesan aktivitas

Mari kita telusuri diagram urutan sebelumnya dengan fokus pada kedatangan aktivitas pesan.

Saluran mengirim pesan pengguna ke Azure AI Bot Service, dan layanan meneruskan pesan ke titik akhir olahpesan bot. Respons bot dikirim ke pengguna dalam cakupan giliran.

Dalam contoh di atas, bot membalas aktivitas pesan dengan aktivitas pesan lain yang berisi pesan teks yang sama. Pemrosesan dimulai dengan permintaan HTTP POST, dengan informasi aktivitas yang dibawa sebagai payload JSON, tiba di server web. Seringkali, proyek ASP.NET digunakan untuk bot C#, dan kerangka kerja populer seperti Express atau restify digunakan untuk Bot Node.js JavaScript.

Adaptor, komponen terintegrasi dari SDK, adalah inti dari runtime SDK. Aktivitas ini dibawa sebagai JSON di bodi HTTP POST. JSON ini dideserialisasi untuk membuat objek aktivitas yang kemudian diserahkan ke adaptor melalui metode aktivitas prosesnya. Saat menerima aktivitas, adaptor membuat konteks giliran dan memanggil middleware.

Seperti disebutkan di atas, konteks giliran menyediakan mekanisme bagi bot untuk mengirim aktivitas keluar, paling sering sebagai respons terhadap aktivitas masuk. Konteks giliran menyediakan metode kirim, perbarui, dan hapus respons aktivitas. Setiap metode respons berjalan dalam proses asinkron.

Penting

Alur yang menangani giliran bot utama menangani pembuangan objek konteks saat selesai. Pastikan untuk await setiap panggilan aktivitas sehingga utas utama akan menunggu aktivitas yang dihasilkan sebelum menyelesaikan pemrosesan dan membuang konteks giliran. Jika tidak, jika respons (termasuk penangannya) membutuhkan waktu yang signifikan dan mencoba bertindak pada objek konteks, mungkin mendapatkan konteks kesalahan yang dibuang .

Template bot

Anda perlu memilih penggunaan lapisan aplikasi untuk aplikasi Anda; namun, Kerangka Kerja Bot memiliki templat dan sampel untuk ASP.NET (C#), restify (JavaScript), dan aiohttp (Python). Dokumentasi ditulis dengan asumsi Anda menggunakan salah satu platform ini, tetapi SDK tidak memerlukannya dari Anda. Lihat mulai cepat Membuat bot untuk instruksi tentang cara mengakses dan menginstal templat.

Bot adalah aplikasi web, dan templat disediakan untuk setiap versi bahasa SDK. Semua templat menyediakan implementasi dan adaptor titik akhir default. Setiap templat meliputi:

• Provisi sumber daya
• Implementasi titik akhir HTTP khusus bahasa yang merutekan aktivitas masuk ke adaptor.
• Objek adaptor
• Objek bot

Perbedaan utama antara berbagai jenis templat ada di objek bot. Templatnya adalah:

• Bot kosong
  • Menyertakan handler aktivitas yang menyambut pengguna ke percakapan dengan mengirim pesan "halo dunia" pada giliran pertama percakapan.
• Bot Echo
  • Menggunakan handler aktivitas untuk menyambut pengguna dan menggemakan kembali input pengguna.
• Bot inti
  • Menyatukan banyak fitur SDK dan menunjukkan praktik terbaik untuk bot.
  • Menggunakan handler aktivitas untuk menyambut pengguna.
  • Menggunakan dialog komponen dan dialog turunan untuk mengelola percakapan.
  • Dialog menggunakan fitur Pemahaman Bahasa (LUIS) dan QnA Maker.

Catatan

Azure AI QnA Maker akan dihentikan pada 31 Maret 2025. Mulai 1 Oktober 2022, Anda tidak akan dapat membuat sumber daya atau basis pengetahuan QnA Maker baru. Versi kemampuan pertanyaan dan jawaban yang lebih baru sekarang tersedia sebagai bagian dari Bahasa Azure AI.

Jawaban atas pertanyaan kustom, fitur Bahasa Azure AI, adalah versi terbaru dari layanan QnA Maker. Untuk informasi selengkapnya tentang dukungan tanya jawab di Bot Framework SDK, lihat Pemahaman bahasa alami.

Catatan

Pemahaman Bahasa (LUIS) akan dihentikan pada 1 Oktober 2025. Mulai 1 April 2023, Anda tidak akan dapat membuat sumber daya LUIS baru. Versi pemahaman bahasa yang lebih baru sekarang tersedia sebagai bagian dari Bahasa Azure AI.

Pemahaman bahasa percakapan (CLU), fitur Bahasa Azure AI, adalah versi LUIS yang diperbarui. Untuk informasi selengkapnya tentang dukungan pemahaman bahasa di Bot Framework SDK, lihat Pemahaman bahasa alami.

Informasi Tambahan

Mengelola sumber daya bot

Anda harus mengelola sumber daya untuk bot Anda, seperti ID aplikasi dan kata sandinya, dan juga informasi untuk layanan yang terhubung. Saat Anda menyebarkan bot Anda, bot akan memerlukan akses aman ke informasi ini. Untuk menghindari kompleksitas, sebagian besar artikel Bot Framework SDK tidak menjelaskan cara mengelola informasi ini.

• Untuk informasi keamanan umum, lihat Panduan keamanan Kerangka Kerja Bot.
• Untuk mengelola kunci dan rahasia di Azure, lihat Tentang Azure Key Vault.

Adaptor saluran

SDK juga memungkinkan Anda menggunakan adaptor saluran, di mana adaptor itu sendiri juga melakukan tugas yang biasa dilakukan Bot Connector Service untuk saluran.

SDK menyediakan beberapa adaptor saluran dalam beberapa bahasa. Lebih banyak adaptor saluran tersedia melalui repositori Botkit dan Komunitas. Untuk informasi selengkapnya, lihat tabel saluran dan adaptor repositori Bot Framework SDK.

REST API Konektor Bot

Bot Framework SDK membungkus dan membangun pada Bot Connector REST API. Jika Anda ingin memahami permintaan HTTP yang mendasar yang mendukung SDK, lihat artikel Autentikasi konektor dan terkait. Aktivitas yang dikirim dan diterima bot sesuai dengan skema Aktivitas Kerangka Kerja Bot.

Langkah berikutnya

• Untuk memahami peran status dalam bot, lihat mengelola status.
• Untuk memahami konsep utama pengembangan bot untuk Microsoft Teams, lihat Cara kerja bot Microsoft Teams