Perluas agen Anda dengan fitur dari REST API (pratinjau)

Note

Artikel ini menjelaskan fitur yang digunakan oleh agen atau alur agen yang didukung oleh standard harness.

[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 Copilot Studio dengan tiga hal:

• 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

Anda dapat menambahkan REST API 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 yang siap untuk produksi, silakan lihat Gambaran Umum Microsoft Copilot Studio.

Copilot agen memungkinkan pembuat menggabungkan beberapa sumber data seperti konektor, API, permintaan, dan sumber pengetahuan ke dalam satu agen. Gunakan agen ini untuk memperluas pengalaman agen bermerk 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.

Note

Anda harus membuat alat REST API dari spesifikasi OpenAPI v2. Persyaratan ini disebabkan oleh perilaku Power Platform dalam memproses spesifikasi API. Jika Anda mengirimkan spesifikasi v3, proses pembuatan secara otomatis menerjemahkannya ke spesifikasi v2.

Prerequisites

• Kredensial tingkat pencipta, dan lisensi Copilot Studio.
• Salinan spesifikasi OpenAPI untuk REST API yang ingin Anda sambungkan
• Pengetahuan tentang jenis autentikasi yang diperlukan untuk terhubung ke API, dan detail otentikasi.

Menambahkan alat REST API ke agen Anda

Untuk menambahkan alat REST API ke agen Anda, selesaikan langkah-langkah berikut:

1. Tambahkan alat agen baru dan pilih REST API
2. Memberikan spesifikasi, deskripsi, dan solusi API
3. Berikan detail autentikasi
4. Pilih alat dari API
5. Meninjau dan menerbitkan

Bagian berikut memandu Anda melalui prosesnya, langkah demi langkah.

Proses untuk menambahkan REST API sama untuk agen kustom dan agen Microsoft 365 Copilot.

Tambahkan alat agen baru dan pilih REST API

1. Buka halaman Ringkasan 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.

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

   

   Note

   Spesifikasi OpenAPI harus berupa file JSON dalam format v2. Jika Anda mengirimkan spesifikasi v3, proses pembuatan secara otomatis menerjemahkannya ke spesifikasi v2.

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

   

   Dalam langkah-langkah berikut, prosedur menggunakan 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.

   

   Bidang 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 guna memberikan lebih banyak data untuk memperbaiki catatan.

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. Pelajari selengkapnya tentang solusi dalam 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 kolom solusi kosong, solusi akan dibuatkan untuk Anda dengan nama tindakan dan penerbit default. Menyimpan tindakan Anda dalam solusi memungkinkan Anda memindahkannya dengan mudah di seluruh lingkungan.

   Note

   Jika Anda tidak melihat solusi default atau solusi default CDS sebagai opsi dalam hal ini, tambahkan solusi kustom untuk manajemen yang mudah. Pelajari selengkapnya di Solusi default vs. solusi kustom.

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

Berikan detail autentikasi

Halaman Autentikasi muncul. Pilih jenis autentikasi yang akan digunakan untuk API.

1. Pilih metode autentikasi dari daftar. Pilih dari tiga opsi:

   • None: Tidak diperlukan otentikasi untuk mengakses API.
   • Kunci API: Pilih opsi ini jika API Anda memerlukan kunci API untuk autentikasi. Saat runtime, saat agen ingin menggunakan alat API, agen meminta pengguna untuk mengautentikasi. Pengguna memberikan kunci API dan agen terhubung ke API menggunakan kunci tersebut.
   • Autentik 2.0: Pilih opsi ini jika server MCP Anda menggunakan OAuth 2.0 untuk autentikasi. OAuth 2.0 memungkinkan pengguna individu mengautentikasi ke API melalui penyedia identitas. Metode autentikasi ini memungkinkan pengguna memberikan izin ke aplikasi (agen) Anda tanpa membagikan kredensial mereka dengan agen.

2. Masukkan bidang yang harus diisi untuk metode autentikasi yang dipilih. Bidang bervariasi berdasarkan metode autentikasi.

   • Tidak ada: Tidak ada informasi yang harus diberikan.
   • Kunci API:
     • Label parameter: Label teks untuk parameter API untuk disajikan kepada pengguna.
     • Nama parameter: Nama aktual untuk parameter kunci API yang akan digunakan di string header atau kueri.
     • Lokasi parameter: Cara Anda mengirim kunci untuk API. Pilih Header atau Query.
   • Auth 2.0:
     • ID Klien: Pengidentifikasi klien yang dikeluarkan oleh penyedia identitas ketika Anda mendaftarkan aplikasi Anda. ID klien memungkinkan penyedia identitas mengetahui aplikasi apa yang membuat permintaan.
     • Rahasia klien: Rahasia dari klien yang dikeluarkan oleh penyedia identitas saat Anda mendaftarkan aplikasi Anda. Agen Anda mengirim rahasia klien bersama dengan ID klien untuk membuktikan bahwa agen Anda berwenang untuk meminta token akses untuk server MCP.
     • URL Otorisasi: Titik akhir penyedia identitas tempat agen Anda mengalihkan pengguna untuk masuk dan memberikan izin kepada agen Anda (kartu persetujuan yang disajikan dalam obrolan agen). Pengguna mengautentikasi di sini lalu penyedia identitas merespons kembali ke agen di URL panggilan balik dengan kode otorisasi.
     • URL token: Titik akhir tempat agen Anda menukar kode otorisasi (atau token refresh) dengan token akses dan token refresh. Token akses memungkinkan agen Anda menggunakan server MCP atas nama pengguna. Token refresh memungkinkan agen Anda mendapatkan akses baru dan menyegarkan token dari titik akhir refresh saat token akses sebelumnya kedaluwarsa.
     • URL Refresh: Titik akhir untuk meminta token akses baru menggunakan token refresh (sehingga pengguna tidak perlu masuk lagi saat token kedaluwarsa).
     • Cakupan: (Opsional): Izin yang diminta aplikasi Anda, berupa daftar yang dipisahkan oleh spasi.
     • Organisasi Microsoft 365 mana yang mengakses titik akhir: Pengaturan ini membatasi akses ke sumber kepada organisasi pembuat, atau semua organisasi. Pilih salah satu:
       • Hanya organisasi saya
       • Setiap organisasi Microsoft 365
     • Aplikasi (klien) mana 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. Saat Anda menyelesaikan semua bidang, pilih Berikutnya.

   Halaman Pilih dan konfigurasikan alat Anda muncul di mana Anda dapat memilih alat untuk diaktifkan dari API.

   

Pilih alat dari API

Pilih alat yang didukung API dari REST API untuk ditambahkan ke agen Anda. Umumnya, REST API menawarkan berbagai alat melalui berbagai kombinasi metode endpoint dan HTTP (get, put, post, delete, 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 kemampuan untuk memperbarui dan menghapus, tetapi Anda hanya ingin pengguna agen Anda dapat membuat rekaman.

1. Pilih alat dari daftar untuk dikonfigurasi.

   Halaman Konfigurasikan alat Anda ditampilkan.

   

2. Konfigurasikan nama dan deskripsi untuk alat yang dipilih. Mirip dengan API keseluruhan, berikan Nama alat dan Deskripsi alat. Deskripsi awalnya diisi otomatis berdasarkan deskripsi dalam spesifikasi API. Nama tidak perlu unik tetapi harus mewakili alat itu sendiri. Deskripsi, seperti halnya deskripsi API secara keseluruhan, harus cukup spesifik untuk memberikan detail kepada model bahasa untuk mengidentifikasi dengan lebih baik apakah kueri Anda selaras dengan alat khusus ini.

3. Setelah bidang diisi, pilih Berikutnya.

   Halaman Tinjau parameter alat Anda ditampilkan.

   

   Halaman ini menunjukkan nilai yang diharapkan untuk input dan nilai output yang dikembalikan. Anda tidak dapat mengubah nilai-nilai ini, tetapi Anda dapat memperbarui deskripsi input dan output. Semua konten di halaman ini ditarik langsung dari spesifikasi API yang diunggah.

4. Perbarui deskripsi sesuai kebutuhan. Deskripsi memberikan definisi tentang untuk apa nilai digunakan. Jika salah satu deskripsi kosong, Anda harus menyelesaikannya sebelum dapat melanjutkan. Anda dapat menempelkan nama 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 alat lain dari API 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 terbitkan

1. Jika Anda perlu membuat pembaruan apa pun, pilih Kembali dan buat perubahan Anda. Jika tidak, pilih Berikutnya.

   Sebuah layar muncul yang menunjukkan bahwa alat Anda sedang diterbitkan sementara proses berlangsung. Anda akan diberi tahu setelah publikasi selesai.

2. Pilih Buat koneksi untuk melanjutkan. Anda akan kembali ke layar Tambahkan alat .

3. Pilih REST API di pemilih jenis alat. Anda dapat melihat alat yang baru dibuat dari API Anda. Harus ada satu entri per alat yang Anda tambahkan dari API.

4. Untuk setiap alat yang baru dikonfigurasi dari API, buat atau pilih koneksi ke API dan tambahkan alat ke agen Anda:

   1. Pada layar Tambahkan alat , pilih alat.
   2. Di bawah Koneksi, pilih koneksi yang ada atau pilih Buat koneksi baru.
   3. Masukkan informasi apa pun yang diperlukan untuk koneksi, lalu pilih Buat untuk membuat koneksi ke alat.
   4. Pilih Tambahkan dan konfigurasikan untuk menambahkan alat ke agen Anda.

   

Alat dari REST API sekarang tersedia untuk digunakan di agen Anda.

Tip

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