Perluas agen Anda dengan fitur dari REST API (pratinjau)

[Artikel ini adalah dokumentasi prarilis dan dapat berubah.]

Anda dapat menggunakan REST API (termasuk OpenAI API) untuk menghubungkan agen yang Anda buat dengan sistem eksternal dan mengakses data yang tersedia untuk digunakan dalam agen Anda. Anda dapat menghubungkan agen Anda ke REST API dengan menyediakan tiga hal untuk Copilot Studio:

• Spesifikasi OpenAPI yang menentukan fungsi API dan tindakan yang tersedia
• Detail tentang jenis autentikasi yang diperlukan dan detail autentikasi bagi pengguna untuk terhubung ke API untuk mengakses sistem eksternal
• Deskripsi untuk membantu model bahasa menentukan kapan harus memanggil API untuk memanfaatkan data

REST API dapat ditambahkan ke agen Copilot dan agen kustom melalui Copilot Studio.

Penting

Artikel ini berisi dokumentasi pratinjau Microsoft Copilot Studio dan dapat berubah.

Fitur pratinjau tidak dimaksudkan untuk penggunaan produksi dan mungkin memiliki fungsionalitas terbatas. Fitur ini tersedia sebelum rilis resmi agar Anda bisa memperoleh akses awal dan memberikan tanggapan.

Jika Anda membangun agen siap produksi, lihat Gambaran umum Microsoft Copilot Studio.

Agen copilot memungkinkan pembuat menggabungkan beberapa sumber data seperti konektor, API, perintah, dan sumber pengetahuan menjadi satu agen. Anda dapat menggunakan agen ini untuk memperluas pengalaman agen bermerek Microsoft seperti Microsoft 365 Copilot.

Agen kustom adalah agen mandiri yang berisi konektor, API, perintah, dan sumber pengetahuan. Anda dapat menggunakan agen khusus secara langsung dengan mengintegrasikannya ke situs web atau saluran lain.

Catatan

Alat REST API harus dibuat dari spesifikasi OpenAPI v2. Persyaratan ini disebabkan oleh perilaku Power Platform dalam pemrosesan spesifikasi API. Jika spesifikasi v3 dikirimkan, spesifikasi tersebut secara otomatis diterjemahkan ke spesifikasi v2 selama proses pembuatan.

Prasyarat

Beberapa prasyarat diperlukan untuk memperluas pengalaman agen bermerek Microsoft dengan tindakan konektor.

Untuk semua jenis pengalaman agen, Anda harus memiliki kredensial tingkat pembuat, dan lisensi Copilot Studio.

Anda juga memerlukan salinan spesifikasi OpenAPI, pengetahuan tentang jenis otentikasi yang diperlukan, dan detail autentikasi.

Menambahkan tindakan REST API ke agen

Menambahkan REST API ke agen Anda melibatkan beberapa langkah. Bagian berikut menjelaskan kepada Anda prosesnya.

Proses untuk menambahkan REST API identik untuk agen Copilot dan kustom.

Ada beberapa langkah dalam prosesnya.

Menambahkan tindakan ke agen

1. buka halaman Gambaran Umum agen Anda.

   

2. Di bagian Alat , pilih Tambahkan alat. Anda juga dapat membuka tab Alat dan memilih Tambahkan alat.

   Halaman Tambahkan alat ditampilkan.

3. Pilih alat baru>REST API.

Berikan spesifikasi, deskripsi, dan solusi API

1. Unggah file spesifikasi OpenAPI untuk REST API yang ingin Anda sambungkan. Anda dapat menyeret dan melepas file spesifikasi ke layar Unggah REST API atau menelusuri sistem Anda untuk menemukan file yang ingin Anda gunakan.

   

   Catatan

   Spesifikasi OpenAPI harus berupa file JSON dalam format v2. Jika spesifikasi v3 dikirimkan, spesifikasi tersebut secara otomatis diterjemahkan ke spesifikasi v2 selama proses pembuatan.

   Setelah Anda mengunggah spesifikasi, layar akan diperbarui untuk menunjukkan nama file spesifikasi dan detailnya.

   

   Dalam langkah-langkah berikut, kami mendasarkan prosedur dalam contoh spesifik SunnyADO, sistem manajemen tiket ADO. Dalam contoh, tujuannya adalah untuk memungkinkan pengguna mengambil dan memperbarui tiket mereka melalui agen.

2. Verifikasi detailnya, lalu pilih Berikutnya.

   Anda disajikan dengan halaman detail plugin API tempat Anda dapat memberikan informasi tambahan tentang API.

   

   Kolom deskripsi awalnya diisi berdasarkan deskripsi dalam spesifikasi API yang Anda unggah. Berikan deskripsi terperinci, sebab orkestrasi agen Anda menggunakan deskripsi untuk menentukan kapan menggunakan alat yang dimaksud. Berikan detail, termasuk sinonim, untuk membantu agen Anda dalam proses seleksi.

   Misalnya, deskripsi awal yang diberikan adalah: "Layanan sederhana untuk mengelola tiket."

   Deskripsi yang lebih baik adalah: "Sistem yang digunakan untuk mendapatkan, mengambil, menemukan, dan menampilkan tiket yang ada dari SunnyADO. Ini memungkinkan pengguna untuk memperbarui, mengubah, dan mengelola tiket untuk menyediakan lebih banyak data untuk meningkatkan memperbaiki rekaman."

3. Masukkan deskripsi yang disempurnakan di bawah bidang Deskripsi.

4. Di bawah Solusi, menu dropdown mencantumkan semua solusi yang tersedia dalam lingkungan saat ini. Pilih solusi yang ingin Anda gunakan. Untuk informasi selengkapnya tentang apa itu solusi, lihat Konsep solusi.

   

   Jika Anda memiliki solusi pilihan, atau konektor yang Anda pilih sudah ada dalam solusi, solusi tersebut akan dipilih secara otomatis.

   Anda dapat memilih solusi atau membiarkannya kosong. Jika Anda membiarkan solusi kosong, solusi dibuat untuk Anda dengan nama tindakan dan penerbit default. Menyimpan tindakan Anda dalam solusi memungkinkan Anda memindahkannya dengan mudah di seluruh lingkungan.

   Catatan

   Jika Anda tidak melihat solusi default atau solusi default CDS sebagai opsi dalam hal ini kami sarankan untuk memiliki solusi khusus untuk pengelolaan yang mudah. Untuk informasi selengkapnya, lihat: Solusi default vs. solusi kustom.

5. Dengan solusi yang dipilih, pilih Berikutnya untuk melanjutkan.

Berikan detail otentikasi

Halaman Autentikasi ditampilkan, untuk memilih jenis autentikasi yang akan digunakan untuk API.

Catatan

Saat ini opsi yang tersedia adalah Tidak Ada, Auth 2.0, dan API.

1. Pilih metode autentikasi dari daftar.

2. Isi bidang yang harus diisi untuk metode otentikasi. Bidang bervariasi berdasarkan metode autentikasi.

   • Tidak ada: Tidak ada bidang lain yang diperlukan.
   • Kunci API:
     • Label Parameter: Label teks untuk parameter API.
     • Nama Parameter: Nama teks untuk parameter API.
     • Lokasi Parameter: Posisi di mana parameter dapat ditemukan.
   • Auth 2.0:
     • ID Klien: GUID klien untuk layanan target.
     • Rahasia Klien – Nilai rahasia untuk klien. Rahasia tidak ditampilkan saat pengguna membuka panel edit setelahnya. Namun, simpan rahasianya, karena Anda akan membutuhkannya jika Anda memilih untuk melakukan pengeditan lebih lanjut.
     • URL otorisasi: URL yang digunakan untuk mengotorisasi sistem sumber.
     • URL token: URL tempat token dapat diambil.
     • URL refresh: URL yang Anda alihkan dalam skenario refresh.
     • Cakupan: URL Cakupan yang ditetapkan ke API untuk aplikasi Microsoft Entra.
     • Organisasi Microsoft 365 mana yang mengakses titik akhir: Ini membatasi akses sumber ke organisasi pembuat, atau semua organisasi.
     • Aplikasi mana (Klien) yang dapat menggunakan titik akhir: GUID yang menentukan sistem klien yang dapat digunakan untuk mengakses data ini. Aplikasi dapat mencakup Microsoft 365, Power Automate, dan opsi lainnya.

3. Setelah semua bidang diisi, pilih Berikutnya.

   Anda akan melihat halaman Pilih dan konfigurasikan alat plugin di mana Anda dapat memilih alat yang akan diaktifkan untuk API.

   

Pilih alat untuk API

Pilih alat yang didukung API untuk diaktifkan. Umumnya, REST API menawarkan berbagai alat melalui berbagai kombinasi titik akhir dan metode HTTP (dapatkan, letakkan, posting, hapus, dan sebagainya) yang ditentukan dalam spesifikasi API. Dalam beberapa kasus, Anda mungkin tidak ingin pengguna agen memiliki kemampuan untuk menjalankan setiap tindakan yang umumnya ditawarkan API. Misalnya, spesifikasi API Anda mungkin menyertakan tindakan untuk memperbarui dan menghapus, tetapi Anda hanya ingin pengguna agen Anda dapat membuat rekaman.

1. Pilih alat dari daftar untuk dikonfigurasi.

   Halaman Konfigurasikan tindakan plugin Anda ditampilkan.

   

2. Konfigurasikan tindakan yang dipilih. Seperti halnya API keseluruhan, Anda diminta untuk memberikan nama Alat dan Deskripsi alat. Deskripsi awalnya diisi sebelumnya dari deskripsi dalam spesifikasi API. Nama tidak perlu unik tetapi harus mewakili alat itu sendiri. Deskripsi, seperti deskripsi API keseluruhan, harus cukup spesifik untuk memberikan detail model bahasa untuk mengidentifikasi dengan lebih baik bahwa kueri Anda selaras dengan alat khusus ini.

3. Setelah bidang diisi, pilih Berikutnya.

   Halaman Tinjau parameter alat Anda ditampilkan.

   

   Halaman ini menunjukkan nilai yang disediakan sebagai bagian dari kemungkinan nilai input dan output. Nilai-nilai ini tidak dapat diubah, namun, deskripsi input dan output dapat diperbarui. Semua konten di halaman ini ditarik langsung dari spesifikasi API yang diunggah.

4. Isi nilai sesuai kebutuhan untuk deskripsi. Deskripsi memberikan definisi tentang untuk apa nilai digunakan. Jika salah satu deskripsi kosong, deskripsi tersebut harus diselesaikan sebelum Anda dapat melanjutkan. Anda dapat menempelkan namanya jika Anda tidak memiliki deskripsi yang lebih baik.

5. Setelah menyelesaikan deskripsi, pilih Berikutnya.

   Alat pertama sekarang dikonfigurasi dan muncul dalam daftar Alat yang dipilih di halaman Pilih dan konfigurasikan alat plugin Anda .

   

6. Tambahkan tindakan lain yang ingin Anda sertakan saat ini. Setelah selesai menambahkan alat yang ingin didukung agen, pilih Berikutnya.

   Halaman Tinjau alat Anda ditampilkan. Halaman ini menyediakan detail alat REST API yang dikonfigurasi.

   

Tinjau dan publikasikan

1. Jika perlu melakukan pembaruan, Anda dapat memilih Kembali dan membuat perubahan. Atau, Pilih Berikutnya.

   Layar ditampilkan yang menunjukkan bahwa alat Anda sedang diterbitkan selama penyelesaian proses. Anda akan diberi tahu setelah publikasi selesai.

2. Setelah penerbitan selesai, Anda dikembalikan ke layar Pilih alat . Di sini Anda dapat menambahkan REST API yang baru dikonfigurasi ke dalam agen Copilot atau agen kustom Anda dan menyelesaikan konfigurasi komponen.

   

Alat REST API sekarang tersedia untuk digunakan di agen Anda.

Tip

Untuk menemukan alat Anda dengan lebih mudah, gunakan bilah Pencarian untuk menemukannya.