Membuat agen data

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Agen data percakapan memungkinkan Anda berinteraksi dengan data database menggunakan antarmuka bahasa alami. Dengan membangun agen ini, Anda membantu pengguna "berinteraksi dengan data mereka", sehingga memperoleh insight dari database operasional tanpa mengharuskan mereka menulis kueri SQL yang kompleks.

Secara umum, agen data adalah kombinasi persona, sekumpulan sumber data, dengan akses ke sekumpulan pengetahuan bisnis yang penting untuk tujuannya.

Bagi developer aplikasi, agen ini memberikan manfaat berikut:

• Akurasi tinggi: dengan menggunakan konteks yang dibuat, Anda dapat mencapai akurasi tinggi untuk pertanyaan bisnis tertentu. Konteks yang ditulis adalah faktor kunci utama yang dapat digunakan pembuat agen untuk meningkatkan akurasi. Ini mencakup deskripsi skema, petunjuk sistem, dan konteks terstruktur yang memberikan informasi tambahan tentang kueri database yang diharapkan.
• Mengurangi kompleksitas: agen menerjemahkan bahasa alami menjadi kueri SQL, eksekusi, dan bahkan perangkuman atau visualisasi data.
• Fleksibilitas: Anda dapat membuat draf agen untuk pengujian pribadi, atau Anda dapat memublikasikannya agar tersedia bagi pengguna lain dalam project Anda atau secara terprogram menggunakan API.

Sebelum memulai

1. Pastikan penagihan diaktifkan untuk project Google Cloud Anda.

2. Aktifkan Cloud SQL, Data Analytics API with Gemini, dan Gemini for Google Cloud API, jika ada yang belum diaktifkan.

   Peran yang diperlukan untuk mengaktifkan API

   Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

   Aktifkan API

Peran yang diperlukan

Untuk menggunakan agen data, Anda harus memiliki izin IAM yang sesuai dengan kasus penggunaan Anda. Tabel berikut mencantumkan peran yang diperlukan berdasarkan apakah Anda membuat dan memublikasikan agen, menyediakan agen di Gemini Enterprise, atau menemukan dan menggunakan agen. Untuk mengetahui informasi selengkapnya, lihat Peran IAM Conversational Analytics API.

Kasus penggunaan	Peran yang diperlukan
Membuat, mengedit, memublikasikan, membagikan, dan menghapus agen	Untuk membuat agen data dalam project: Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) di project. Peran ini otomatis memberi Anda peran Pemilik Agen Data Gemini Data Analytics pada agen data yang Anda buat. Untuk mengedit, membagikan, atau menghapus agen data: Pemilik Agen Data Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) di agen atau project. Untuk mengedit agen data dalam project: Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) di project. Untuk melihat agen data dalam project: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) di project. Selain itu, Anda harus memiliki peran berikut untuk membuat atau mengedit agen data: Akun pengguna atau layanan IAM yang ditambahkan ke instance. Untuk mengetahui informasi selengkapnya, lihat Mengelola pengguna dengan autentikasi database IAM untuk Cloud SQL. Peran cloudsql.studioUser dan cloudsql.instanceUser yang diberikan kepada pengguna IAM di level project. Untuk mengetahui informasi selengkapnya, lihat Menambahkan binding kebijakan IAM untuk project. Opsional: Jika Anda menggunakan set konteks (Pratinjau) dengan agen data database, untuk membuat, mengupload, dan mengelola set konteks: peran Dataplex Catalog Editor (roles/dataplex.catalogEditor) atau Dataplex Catalog Admin (roles/dataplex.catalogAdmin) yang diberikan kepada pengguna IAM di level project. Untuk mengetahui informasi selengkapnya, lihat Izin set konteks. Hak istimewa database yang diberikan kepada pengguna atau akun layanan IAM dengan login sebagai pengguna postgres. GRANT ALL ON SCHEMA public TO public; Untuk mengetahui informasi selengkapnya, lihat Memberikan hak istimewa database kepada setiap pengguna atau akun layanan IAM.
Menyediakan agen di Gemini Enterprise	Agar agen yang dipublikasikan tersedia bagi pengguna di Gemini Enterprise, Anda memerlukan izin untuk mendaftarkan dan mengelola agen A2A di konsol administrasi Gemini Enterprise.
Menemukan dan menggunakan agen	Untuk melakukan chat dengan agen data: Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser). Untuk melihat semua agen data dalam project: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer).

Saat Anda mengelola akses ke resource database Cloud SQL untuk PostgreSQL, pertimbangkan lapisan izin berikut:

• Google Cloud IAM: mengontrol akses ke instance database sebagai resource cloud. Hal ini mencakup izin untuk terhubung, mengelola instance, dan menjalankan kueri SQL, misalnya, menggunakan izin executeSql.
• Izin database: mengontrol akses ke objek dalam database—seperti tabel, tampilan, dan skema. Izin ini dikelola menggunakan perintah SQL seperti GRANT dan sistem peran serta pengguna khusus database.

Untuk Cloud SQL untuk PostgreSQL, Anda memerlukan peran IAM Cloud SQL yang sesuai untuk terhubung ke instance dan diberi otorisasi untuk mengirim kueri. Untuk berinteraksi dengan objek seperti tabel dan tampilan, pengguna database yang terhubung harus memiliki hak istimewa yang diperlukan yang diberikan menggunakan sistem GRANT Cloud SQL untuk PostgreSQL. Untuk mengetahui informasi selengkapnya, lihat Tentang pengguna dan peran PostgreSQL. Jika agen menggunakan akun layanan, Anda bisa mendapatkan peran database yang ditetapkan. Misalnya, lihat Mengelola pengguna dengan autentikasi database IAM.

Membuat agen data

Bagian berikut menjelaskan cara membuat agen data. Setelah membuat agen, Anda dapat mengedit setelannya.

Mengonfigurasi dasar-dasar

1. Di konsol Google Cloud , buka halaman Cloud SQL untuk PostgreSQL.

   Buka Cloud SQL

2. Pilih instance dari daftar.

3. Di menu navigasi, klik Conversations.

4. Klik tab Agen.

5. Pilih database dan login menggunakan akun IAM Anda.

6. Klik New agent. Halaman New agent akan terbuka.

7. Di bagian Editor, di kolom Agent name, masukkan nama deskriptif untuk agen data—misalnya, Q4 sales data atau User activity logs.

8. Di kolom Agent description, masukkan deskripsi agen data. Deskripsi yang baik menjelaskan apa yang dilakukan agen, data apa yang digunakannya, dan membantu Anda menentukan apakah ini adalah agen data yang tepat untuk digunakan dalam percakapan—misalnya, What are the top 10 selling products in Q2?

9. Di bagian Knowledge sources, klik Add source. Halaman Add data akan terbuka.

10. Pilih tabel yang akan difokuskan agen saat menjawab pertanyaan. Untuk melihat sumber informasi tambahan, pilih Tampilkan lainnya.

11. Klik Tambahkan. Halaman agen baru akan dibuka kembali.

Menyesuaikan deskripsi tabel dan kolom

Untuk meningkatkan akurasi agen data percakapan, Anda dapat memberikan metadata tabel tambahan secara opsional. Hanya agen data yang menggunakan metadata ini, dan metadata ini tidak memengaruhi tabel sumber. Anda dapat menambahkan metadata berikut:

• Deskripsi skema: tambahkan deskripsi untuk tabel dan kolom Anda guna membantu agen memahami data Anda. Jika Anda tidak menambahkan deskripsi, agen akan menggunakan deskripsi skema dari definisi data Anda.

Ikuti praktik terbaik berikut saat Anda menambahkan deskripsi tabel dan kolom:

• Tambahkan deskripsi ke definisi data, bukan hanya ke definisi agen data. Hal ini memastikan bahwa agen lain juga mendapatkan manfaat dari deskripsi tersebut.
• Untuk membuat prototipe deskripsi yang sesuai guna membantu agen data memahami data Anda, tambahkan deskripsi ke agen tertentu. Setelah memverifikasi bahwa deskripsi memiliki dampak yang diinginkan, Anda dapat memutuskan apakah akan menambahkan deskripsi dalam definisi data Anda.

Untuk menyesuaikan deskripsi tabel dan kolom untuk agen, lakukan langkah-langkah berikut:

1. Di tab Agent Catalog, buka agen yang ingin Anda sesuaikan.
2. Klik Edit Agent.
3. Di Sumber Informasi, temukan tabel yang ingin Anda sesuaikan, lalu klik Sesuaikan.
4. Tambahkan deskripsi di Deskripsi Tabel atau terima saran dari Gemini.
5. Di Fields, tinjau deskripsi yang disarankan Gemini untuk kolom dalam tabel.
6. Kelola deskripsi kolom yang disarankan:
   • Untuk menerima saran, pilih deskripsi yang Anda inginkan, lalu klik Terima saran.
   • Untuk menolak saran, pilih deskripsi yang Anda inginkan, lalu klik Tolak saran.
7. Untuk mengedit deskripsi kolom, klik Edit di samping kolom.
   1. Di Description, masukkan deskripsi kolom.
   2. Klik Perbarui untuk menyimpan hasil edit Anda.
8. Klik Perbarui untuk menyimpan penyesuaian tabel.
9. Ulangi langkah-langkah ini untuk setiap tabel yang ingin Anda sesuaikan.

Membuat kueri terverifikasi

Catatan: Kueri terverifikasi hanya dapat ditambahkan untuk mode "Dipandu"

Anda dapat memilih kueri terverifikasi dari daftar yang dibuat oleh sistem, atau membuat kueri Anda sendiri.

Untuk membuat kueri terverifikasi untuk agen data, lakukan hal berikut:

1. Di tab Agent Catalog, buka agen yang ingin Anda sesuaikan.
2. Klik Edit Agent.

3. Di Kueri terverifikasi, klik Lihat saran yang dibuat oleh Gemini.

   1. Di bagian Tinjau kueri terverifikasi yang disarankan, tinjau kueri terverifikasi yang disarankan.
   2. Pilih kueri yang berlaku untuk kasus penggunaan Anda.
   3. Klik Add untuk menambahkan kueri ke konteks.
   Catatan: Untuk mengedit kueri yang disarankan, luaskan kueri yang disarankan dan klik Edit.

4. Opsional. Untuk membuat kueri terverifikasi Anda sendiri, di Verified queries, klik Add query.

   1. Di Pertanyaan, masukkan pertanyaan yang dapat dijawab oleh kueri yang diverifikasi.
   2. Klik Generate SQL untuk mengizinkan Gemini membuat kueri terverifikasi yang sesuai dengan pertanyaan yang Anda tambahkan.
   3. Klik Run dan pastikan kueri menampilkan hasil yang Anda harapkan.
   4. Tinjau respons dan ubah kueri terverifikasi, jika diperlukan.
   5. Klik Tambahkan.

5. Ulangi langkah-langkah ini untuk membuat kueri terverifikasi tambahan.

Menambahkan label ke agen data

Di bagian Agent Settings, Anda dapat membuat label untuk mengatur resource Google Cloud . Label adalah key-value pair yang dapat Anda gunakan untuk mengelompokkan objek terkait secara bersamaan atau dengan resource Google Cloudlainnya.

1. Di tab Agent Catalog, buka agen yang ingin Anda tambahi label.
2. Klik Edit Agent.
3. Di bagian Agent Settings, klik Add label. Panel Manage labels akan terbuka.
4. Klik Tambahkan label.
5. Di kolom key dan value, masukkan pasangan nilai kunci untuk label.
6. Jika Anda ingin menambahkan label lainnya, klik Tambahkan label lagi.
7. Untuk menghapus label, klik hapus.
8. Setelah selesai, klik Tambahkan. Halaman agen baru akan dibuka kembali.

Lanjutkan ke bagian berikutnya untuk menempatkan agen dalam mode draf atau untuk memublikasikan agen.

Melihat pratinjau dan memublikasikan agen

1. Di bagian Preview, masukkan contoh pertanyaan di kolom Ask a question, lalu tekan Enter.

   Untuk memverifikasi bahwa agen data menampilkan data yang Anda harapkan, tinjau respons agen. Jika responsnya tidak sesuai harapan, ubah setelan di bagian Editor untuk menyaring konfigurasi agen data hingga Anda mendapatkan respons yang memuaskan. Anda dapat terus menguji dan mengubah agen untuk meningkatkan hasil agen.

2. Klik Simpan.

3. Untuk menempatkan agen data dalam mode draf, yang dapat Anda edit ulang nanti, klik Go back untuk kembali ke halaman Agent Catalog. Karena agen Anda sekarang dalam mode draf, agen tersebut akan muncul di bagian My draft agents di tab Agent Catalog.

   Untuk memublikasikan agen, tetap berada di halaman pembuatan agen dan lanjutkan ke langkah berikutnya.

4. Untuk memublikasikan agen data dan membuatnya tersedia untuk digunakan dalam project, klik Publish. Dengan memublikasikan agen, pengguna lain— yang memiliki akses ke tabel database yang sama—dapat melihat dan berkomunikasi dengan agen Anda, serta memanfaatkan petunjuk dan konteks yang Anda buat.

   Anda dapat membuat percakapan dengan agen data menggunakan halaman Conversations di konsol Google Cloud . Anda juga dapat membangun antarmuka sendiri untuk melakukan percakapan dengan agen data menggunakan Conversational Analytics API.

5. Opsional: Di dialog Agen Anda telah dipublikasikan, klik Bagikan untuk membagikan agen data kepada pengguna lain.

   1. Di panel Share permissions, klik Add principal.
   2. Di kolom New principals, masukkan satu atau beberapa akun utama.
   3. Klik daftar Select a role.
   4. Di daftar Role, pilih salah satu peran berikut:
      • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser): memberikan izin untuk melakukan chat dengan agen data.
      • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor): memberikan izin untuk mengedit agen data.
      • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): memberikan izin untuk melihat agen data.
   5. Klik Simpan.

6. Opsional: Anda dapat memublikasikan agen data ke Gemini Enterprise. Untuk mengetahui informasi selengkapnya, lihat Memublikasikan agen data di Gemini Enterprise.

7. Untuk kembali ke halaman agen baru, klik Close. Setelah menyimpan atau memublikasikan agen, Anda dapat melihatnya di Katalog Agen.

Mengelola agen data

Anda dapat menemukan agen yang ada di tab Agent Catalog, yang terdiri dari tiga bagian:

• Agen saya: daftar semua agen yang Anda buat dan publikasikan. Anda dapat mengubah dan membagikan agen yang dipublikasikan kepada orang lain.
• Agen draf saya: agen yang belum Anda publikasikan. Anda tidak dapat membagikan agen draf.
• Dibagikan oleh orang lain dalam organisasi Anda: agen yang dibuat dan dibagikan orang lain kepada Anda. Jika orang lain memberi Anda izin, Anda dapat mengedit agen bersama ini.

Mengedit agen data

Untuk mengedit agen data, ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka halaman Cloud SQL untuk PostgreSQL.

   Buka Cloud SQL

2. Pilih instance dari daftar.

3. Di menu navigasi, klik Conversations.

4. Login ke Conversations menggunakan autentikasi Identity and Access Management (IAM).

5. Klik tab Agent Catalog.

6. Temukan kartu agen dari agen data yang ingin Anda ubah.

7. Untuk membuka agen data di editor agen, klik Open actions, lalu klik Edit di kartu agen.

8. Edit konfigurasi agen data sesuai kebutuhan.

9. Untuk menyimpan perubahan tanpa memublikasikannya, klik Simpan.

10. Untuk memublikasikan perubahan, klik Publikasikan. Dalam dialog Share, Anda dapat membagikan agen kepada orang lain, atau mengklik Cancel.

11. Untuk kembali ke panel Percakapan, klik Kembali.

Membagikan agen data

Ikuti langkah-langkah berikut untuk membagikan agen data yang dipublikasikan. Anda tidak dapat membagikan draf agen.

1. Di konsol Google Cloud , buka halaman Cloud SQL untuk PostgreSQL.

   Buka Cloud SQL

2. Pilih instance dari daftar.

3. Di menu navigasi, klik Conversations.

4. Login ke Conversations menggunakan autentikasi Identity and Access Management (IAM).

5. Klik tab Agent Catalog.

6. Temukan kartu agen dari agen data yang ingin Anda ubah.

7. Untuk membuka agen data di editor agen, klik Open actions > klik Edit di kartu agen.

8. Untuk membagikan agen data kepada pengguna lain, klik Bagikan.

9. Di panel Share permissions, klik Add principal.

10. Di kolom Add principals, masukkan satu atau beberapa akun utama.

11. Klik Pilih peran.

12. Di daftar Role, pilih salah satu peran berikut:

    • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser): memberikan izin untuk melakukan chat dengan agen data.
    • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor): memberikan izin untuk mengedit agen data.
    • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): memberikan izin untuk melihat agen data.

13. Klik Simpan.

14. Untuk kembali ke halaman pengeditan agen, klik Close.

15. Untuk kembali ke panel Percakapan, klik Kembali.

Menghapus agen data

1. Di konsol Google Cloud , buka halaman Cloud SQL untuk PostgreSQL.

   Buka Cloud SQL

2. Pilih instance dari daftar.

3. Di menu navigasi, klik Conversations.

4. Login ke Conversations menggunakan autentikasi Identity and Access Management (IAM).

5. Pilih tab Agent Catalog.

6. Di bagian Agents pada tab Agent Catalog, temukan kartu agen dari agen data yang ingin Anda hapus.

7. Klik Buka tindakan > Hapus.

8. Pada dialog Delete agent?, klik Delete. Menghapus agen akan menghapus agen dari project secara permanen.

   Setelah Anda menghapus agen, percakapan yang ada akan tersedia dalam mode hanya lihat. Anda tidak dapat mengajukan pertanyaan baru kepada agen yang dihapus.

Memublikasikan agen data di Gemini Enterprise

Publikasi agen data melibatkan kolaborasi antara analis data, administrator Gemini Enterprise, dan pengguna bisnis. Untuk mempelajari peran yang diperlukan untuk pengguna ini, lihat Peran yang diperlukan.

Membuat dan memublikasikan agen

Untuk membuat, mengedit, dan memublikasikan agen, ikuti langkah-langkah berikut:

1. Buat atau edit agen data Anda di Cloud SQL untuk PostgreSQL.
2. Publikasikan agen. Saat Anda memublikasikan agen, pilih Gemini Enterprise sebagai opsi publikasi.
3. Untuk menyalin JSON endpoint A2A, klik Salin JSON.
4. Bagikan JSON endpoint A2A dan daftar pengguna kepada administrator Gemini Enterprise Anda agar mereka dapat mendaftarkan agen kustom di konsol Google Cloud dan mengonfigurasi izin akses. Untuk mengetahui informasi selengkapnya, lihat Menyediakan agen.
5. Bagikan agen kepada pengguna dan grup yang memerlukan akses.

Menyediakan agen

Agar agen yang dipublikasikan tersedia bagi pengguna di konsol Google Cloud , ikuti langkah-langkah berikut:

1. Di konsol Google Cloud , buka Gemini Enterprise.

   Gemini Enterprise

2. Klik nama aplikasi tempat Anda ingin mendaftarkan agen.

3. Klik Agents > Add Agents.

4. Di bagian Choose an agent type, klik Add untuk Custom agent via A2A.

5. Di kolom Agent card JSON, masukkan detail kartu agen yang sebelumnya Anda terima dari analis data dalam format JSON.

6. Klik Preview agent details > Next.

7. Agar agen dapat mengakses resource Google Cloud atas nama Anda, ikuti langkah-langkah berikut:

   1. Masukkan client ID dan rahasia klien yang Anda buat di bagian Mengonfigurasi detail otorisasi.

   2. Di kolom Authorization URI, masukkan kode berikut:

      https://accounts.google.com/o/oauth2/v2/auth?client_id=client_id&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

      Ganti client_id dengan client ID yang Anda buat di Mengonfigurasi detail otorisasi.

   3. Di kolom Token URI, masukkan:

      https://oauth2.googleapis.com/token

   4. Di kolom Scopes, masukkan berikut ini:

      https://www.googleapis.com/auth/cloud-platform

8. Klik Selesai.

9. Bagikan agen kepada pengguna atau grup.

Untuk mengetahui informasi selengkapnya, lihat Mendaftarkan dan mengelola agen A2A.

Menemukan dan menggunakan agen

Anda dapat menemukan dan menggunakan agen data di Gemini Enterprise menggunakan salah satu metode berikut:

• Temukan agen di Galeri Agen dan mulai chat khusus.
• Gunakan URL khusus agen untuk membuka Gemini Enterprise langsung ke sesi dengan agen data Cloud SQL untuk PostgreSQL tertentu.
• Panggil agen dengan menulis @mention—seperti @sales_pipeline_agent— di chat inti Gemini Enterprise.
• Ajukan pertanyaan analitis umum—seperti "Bagaimana tren pipeline penjualan kami dalam 3 bulan terakhir?"—untuk memungkinkan Gemini Enterprise secara otomatis mengarahkan kueri ke agen data yang relevan.

Setelah menemukan agen, Anda dapat berinteraksi dengannya menggunakan salah satu metode berikut:

• Selesaikan login OAuth satu kali untuk melakukan autentikasi dengan aman ke Cloud SQL untuk PostgreSQL.
• Mengajukan pertanyaan dalam bahasa alami. Agen analisis percakapan memproses permintaan Anda dan melakukan streaming respons kembali ke Gemini Enterprise sebagai teks, Markdown, diagram, atau tabel.
• Lihat histori percakapan Anda di panel histori, tempat percakapan disimpan secara otomatis.

Lokasi

Analisis percakapan beroperasi secara global; Anda tidak dapat memilih region yang akan digunakan.

Langkah berikutnya

• Pelajari lebih lanjut analisis percakapan di Cloud SQL untuk PostgreSQL.
• Pelajari lebih lanjut Conversational Analytics API.
• Menganalisis data dengan percakapan.
• Pelajari lebih lanjut cara peran Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) memberikan izin untuk melihat agen data.