Membuat agen data untuk Firestore dengan kompatibilitas MongoDB

Agen data percakapan memungkinkan Anda berinteraksi dengan data database menggunakan antarmuka bahasa alami. Dengan membangun agen ini, Anda membantu pengguna "berbicara dengan data mereka", sehingga mendapatkan insight dari database operasional tanpa mengharuskan mereka menulis kueri MongoDB-compatible Query Language (MQL) 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 ditulis, 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.
  • Kompleksitas yang lebih rendah: agen menerjemahkan bahasa alami menjadi kueri MQL, eksekusi, dan bahkan ringkasan 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 Firestore API, Data Analytics API with Gemini, dan Gemini for Google Cloud API, jika 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 informasi selengkapnya, lihat Peran Identity and Access Management 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.
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).

Untuk menggunakan resource Firestore, lihat Peran dan izin Firestore.

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

    Buka Firestore

  2. Pilih database dari daftar. Database harus berjenis Firestore with MongoDB compatibility.

  3. Di menu navigasi, klik Conversations.

  4. Klik tab Agen.

  5. Klik New agent. Halaman New agent akan terbuka.

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

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

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

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

  10. Klik Tambahkan data. Halaman agen baru akan dibuka kembali.

  11. Klik Simpan draf untuk menyimpan progres Anda.

Menyesuaikan deskripsi koleksi dan kolom

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

  • Deskripsi skema: tambahkan deskripsi untuk koleksi dan kolom dokumen 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 koleksi 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 mengonfigurasi deskripsi kolom dokumen dan koleksi, ikuti langkah-langkah berikut:

  1. Di tab Agent Catalog, buka agen yang ingin Anda sesuaikan.
  2. Klik Edit Agent.
  3. Di Sumber Informasi, cari koleksi yang ingin Anda sesuaikan, lalu klik Sesuaikan.
  4. Masukkan deskripsi koleksi.
  5. Untuk mengedit deskripsi kolom, klik Edit di samping kolom. Panel Edit kolom akan terbuka.
    1. Di kolom ID, masukkan deskripsi kolom.
    2. Untuk menyimpan deskripsi kolom, klik Update.
  6. Untuk menyimpan pembaruan deskripsi dan kolom, klik Perbarui. Halaman agen baru akan dibuka kembali.
  7. Ulangi langkah-langkah ini untuk setiap koleksi yang ingin Anda sesuaikan.

Membuat kueri terverifikasi

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.

  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 MQL agar 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 konsol Google Cloud , buka halaman Firestore.

    Buka Firestore

  2. Pilih database dari daftar. Database harus berjenis Firestore with MongoDB compatibility.

  3. Di menu navigasi, klik Conversations.

  4. Klik tab Agent Catalog.

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

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

  7. Di bagian Agent Settings, klik Add label. Panel Kelola label akan terbuka.

  8. Klik Tambahkan label.

  9. Di kolom key dan value, masukkan pasangan nilai kunci untuk label.

  10. Jika Anda ingin menambahkan label lainnya, klik Tambahkan label lagi.

  11. Untuk menghapus label, klik hapus.

  12. 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 dengan yang Anda harapkan, ubah setelan di bagian Editor untuk menyaring konfigurasi agen data hingga Anda mendapatkan respons yang memuaskan. Anda dapat terus menguji dan memodifikasi agen untuk meningkatkan hasil agen.

  2. Klik Simpan draf.

  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 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: Pada dialog Agen Anda telah dipublikasikan dan siap dibagikan., 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 draf agen.
  • 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 Firestore.

    Buka Firestore

  2. Pilih database dari daftar. Database harus berjenis Firestore with MongoDB compatibility.

  3. Di menu navigasi, klik Conversations.

  4. Klik tab Agent Catalog.

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

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

  7. Edit konfigurasi agen data sesuai kebutuhan.

  8. Untuk menyimpan perubahan tanpa memublikasikannya, klik Simpan draf.

  9. Untuk memublikasikan agen data dan membuatnya tersedia untuk digunakan dalam project, klik Publish. Dalam dialog Share, Anda dapat membagikan agen kepada orang lain, atau mengklik Close.

  10. 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 Firestore.

    Buka Firestore

  2. Pilih database dari daftar. Database harus berjenis Firestore with MongoDB compatibility.

  3. Di menu navigasi, klik Conversations.

  4. Klik tab Agent Catalog.

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

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

  7. Untuk membagikan agen data kepada pengguna lain, klik Share.

  8. Di panel Share permissions, klik Add principal.

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

  10. Klik Pilih peran.

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

  12. Klik Simpan.

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

  14. Untuk kembali ke panel Percakapan, klik Kembali.

Menghapus agen data

  1. Di konsol Google Cloud , buka halaman Firestore.

    Buka Firestore

  2. Pilih database dari daftar. Database harus berjenis Firestore with MongoDB compatibility.

  3. Di menu navigasi, klik Conversations.

  4. Pilih tab Agent Catalog.

  5. Cari kartu agen data yang ingin Anda hapus.

  6. Klik Buka tindakan > Hapus.

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

Memublikasikan 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 Firestore.
  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 Pratinjau detail agen > Berikutnya.

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

    1. Masukkan Client ID dan Client secret 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 kode berikut:

      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 Firestore 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 mengarahkan kueri secara otomatis 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 Firestore.
  • Mengajukan pertanyaan dalam bahasa alami. Agen analisis percakapan memproses permintaan Anda dan menstreaming 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