Membangun agen data dan memulai percakapan dengan data Anda

Penting: Data QnA API tidak digunakan lagi. Jika Anda bermigrasi dari Data QnA API, lihat panduan migrasi untuk mengetahui ringkasan perbedaan utama dan langkah-langkah migrasi yang diperlukan.

Developer dapat menggunakan Conversational Analytics API, yang diakses melalui geminidataanalytics.googleapis.com atau endpoint regional, untuk membangun antarmuka chat yang didukung kecerdasan buatan (AI), atau agen data. API ini menggunakan bahasa alami untuk menjawab pertanyaan tentang data terstruktur di BigQuery, Looker, Data Studio, dan sumber data database (AlloyDB, GoogleSQL untuk Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL dalam Pratinjau di v1beta). Selain multi-turn chat, Anda dapat menggunakan metode QueryData untuk menjalankan kueri single-turn.

Dengan Conversational Analytics API, Anda memberikan informasi dan data bisnis (konteks) kepada agen data, serta akses ke alat seperti SQL, Python, dan library visualisasi. Respons agen ini ditampilkan kepada pengguna dan dapat dicatat ke dalam log oleh aplikasi klien, sehingga menciptakan pengalaman chat data yang lancar dan dapat diaudit.

Pelajari cara dan waktu Gemini untuk Google Cloud menggunakan data Anda.

Sebagai teknologi tahap awal, produk Gemini untuk Google Cloud dapat menghasilkan output yang tampak masuk akal, tetapi berisi fakta yang salah. Sebaiknya Anda memvalidasi semua output dari produk Gemini untuk Google Cloud sebelum Anda menggunakannya. Untuk mengetahui informasi selengkapnya, lihat Gemini untuk Google Cloud dan responsible AI.

Mulai menggunakan Conversational Analytics API

Untuk mulai menggunakan Conversational Analytics API, tinjau dokumentasi berikut untuk memahami pendekatan integrasi dan konsep inti yang tersedia:

• Arsitektur dan konsep utama: Pahami cara agen data memproses permintaan, alur kerja untuk pembuat dan pengguna agen, mode percakapan, serta peran Identity and Access Management (IAM) yang diperlukan.
• Pola integrasi untuk agen data: Bandingkan pendekatan arsitektur untuk menentukan metode koneksi terbaik untuk aplikasi Anda.
• Pengelolaan status: Pelajari mode percakapan stateful dan stateless, cara API mengelola histori percakapan, dan cakupan status sesi ADK.
• Keamanan, privasi, risiko, dan kepatuhan: Pahami opsi keamanan dan kepatuhan untuk Conversational Analytics API.
• Lokasi Conversational Analytics API: Memberikan ringkasan endpoint API regional atau multi-regional yang memungkinkan Anda mengontrol lokasi geografis resource, konfigurasi, dan data agen Anda.

Untuk mulai membangun agen data, selesaikan langkah-langkah dalam dokumentasi penyiapan dan prasyarat. Untuk panduan, aplikasi contoh, SDK, dan alat developer lainnya, lihat Tutorial, demo, dan alat Conversational Analytics API.

Penyiapan dan prasyarat

Sebelum Anda menggunakan API atau contoh, selesaikan langkah-langkah berikut:

• Mengaktifkan Conversational Analytics API: Menjelaskan prasyarat untuk mengaktifkan Conversational Analytics API.
• Kontrol akses dengan IAM: Menjelaskan cara menggunakan Identity and Access Management untuk membagikan dan mengelola akses ke agen data.
• Mengautentikasi dan menghubungkan ke sumber data: Memberikan petunjuk untuk mengautentikasi ke API dan mengonfigurasi koneksi ke sumber data BigQuery, Lakehouse, Looker, Data Studio, dan database (AlloyDB, GoogleSQL untuk Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL).
• Menghubungkan ke BigQuery: Menjelaskan peran yang diperlukan dan cara menghubungkan agen data ke tabel dan grafik BigQuery.
• Menghubungkan ke Looker: Menjelaskan cara menghubungkan agen data ke Looker Explore dan melakukan autentikasi ke instance Looker Anda.
• Kunci enkripsi yang dikelola pelanggan (CMEK): Menjelaskan cara menggunakan kunci enkripsi Anda sendiri di Cloud Key Management Service untuk melindungi agen data dan percakapan.
• Batasan kebijakan organisasi: Menjelaskan cara menggunakan batasan kebijakan organisasi yang telah ditetapkan untuk mengontrol resource di tingkat organisasi, folder, atau project.

Membangun dan berinteraksi dengan agen data

Setelah menyelesaikan langkah-langkah sebelumnya, gunakan Conversational Analytics API untuk membangun dan berinteraksi dengan agen data dengan mengikuti langkah-langkah berikut:

• Membangun agen data menggunakan HTTP: Memberikan contoh lengkap cara membangun dan berinteraksi dengan agen data menggunakan permintaan HTTP langsung dengan Python.
• Membangun agen data menggunakan Python SDK: Memberikan contoh lengkap cara membangun dan berinteraksi dengan agen data menggunakan Python SDK.
• Mengorkestrasi agen data dengan A2A: Pelajari cara menemukan kemampuan agen, mendelegasikan kueri analisis, serta melakukan streaming kueri SQL dan visualisasi diagram di seluruh sistem multi-agen.
• Memandu perilaku agen dengan konteks yang ditulis: Pelajari cara memberikan konteks yang ditulis untuk memandu perilaku agen dan meningkatkan akurasi respons. Anda juga dapat melihat contoh konteks yang ditulis dengan sumber data BigQuery dan dengan sumber data Looker.

• Merender respons agen Conversational Analytics API sebagai visualisasi: Memberikan contoh pemrosesan spesifikasi diagram dari respons API dan merendernya sebagai visualisasi menggunakan Python SDK dan library Vega-Altair.

  Catatan: Rendering visualisasi tidak didukung untuk sumber data database (AlloyDB, GoogleSQL untuk Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL).

Praktik terbaik

Tinjau panduan berikut untuk mempelajari praktik terbaik dalam menggunakan Conversational Analytics API:

• Mengelola biaya BigQuery untuk agen Anda: Pelajari cara memantau dan mengelola biaya BigQuery untuk agen Conversational Analytics API Anda dengan menetapkan batas pembelanjaan tingkat project, tingkat pengguna, dan tingkat kueri.
• Mengajukan pertanyaan yang efektif: Pelajari cara menyusun pertanyaan yang efektif untuk agen Anda guna mendapatkan hasil maksimal dari Conversational Analytics API.
• Retensi dan penghapusan data: Pelajari retensi dan penghapusan data untuk agen data dan percakapan Conversational Analytics API.
• Kuota dan batas: Pelajari kuota dan batas untuk Conversational Analytics API.
• Memecahkan masalah error Conversational Analytics API: Memecahkan masalah error Conversational Analytics API yang umum.
• Batasan umum: Memberikan informasi mendetail tentang batasan umum Conversational Analytics API, termasuk batasan kueri, data, visualisasi, dan pertanyaan.
• Merender respons agen untuk sumber data Looker: Pelajari praktik terbaik untuk merender respons API Conversational Analytics di antarmuka pengguna saat Anda menggunakan sumber data Looker.

Referensi API dan library klien

• Referensi REST Gemini Data Analytics: Memberikan deskripsi mendetail tentang versi API, metode, endpoint, dan definisi jenis.
• SDK dan alat developer: Mencantumkan library klien spesifik per bahasa.

Operasi API utama

API ini menyediakan endpoint inti berikut untuk mengelola agen data dan percakapan. Endpoint v1 dalam tabel berikut mendukung sumber data BigQuery, Looker, dan Data Studio. Karena sumber data database berada dalam Pratinjau di v1beta, tentukan jalur /v1beta/ yang sesuai untuk sumber database.

Saat membuat jalur ini (atau nama resource SDK yang sesuai), ganti karakter pengganti (*) dengan project ID, ID lokasi (seperti global atau us), dan ID resource (seperti ID agen atau ID percakapan) jika berlaku.

Penting: Lokasi di jalur permintaan Anda harus cocok dengan lokasi endpoint yang Anda panggil. Misalnya, jika Anda memanggil endpoint geminidataanalytics.us.rep.googleapis.com, tentukan us di jalur permintaan Anda (seperti /locations/us). Untuk mengetahui detail tentang residensi data dan konfigurasi endpoint, lihat Residensi data.

Operasi	Metode HTTP	Endpoint	Deskripsi
Buat agen	POST	/v1/projects/*/locations/*/dataAgents	Membuat agen data baru.
Membuat agen secara sinkron	POST	/v1/projects/*/locations/*/dataAgents:createSync	Membuat agen data baru secara sinkron.
Mendapatkan agen	GET	/v1/projects/*/locations/*/dataAgents/*	Mengambil detail agen data tertentu.
Mendapatkan kebijakan Identity and Access Management	POST	/v1/projects/*/locations/*/dataAgents/*:getIamPolicy	Mendapatkan izin Identity and Access Management yang ditetapkan untuk setiap pengguna untuk agen data tertentu. Pengguna dengan peran Pemilik Agen Data dapat memanggil endpoint ini untuk melihat kebijakan Identity and Access Management agen data sebelum menggunakan endpoint setIAMpolicy untuk membagikan agen data kepada pengguna lain.
Menetapkan kebijakan Identity and Access Management	POST	/v1/projects/*/locations/*/dataAgents/*:setIamPolicy	Menetapkan kebijakan Identity and Access Management untuk agen data tertentu. Pengguna dengan peran Pemilik Agen Data harus memanggil endpoint ini untuk membagikan agen data kepada pengguna lain, yang secara efektif memperbarui izin Identity and Access Management pengguna tersebut.
Memperbarui agen	PATCH	/v1/projects/*/locations/*/dataAgents/*	Mengubah agen data yang ada.
Mengupdate agen secara sinkron	PATCH	/v1/projects/*/locations/*/dataAgents/*:updateSync	Mengubah agen data yang ada secara sinkron.
Mencantumkan agen	GET	/v1/projects/*/locations/*/dataAgents	Mencantumkan agen data yang tersedia dalam project.
Mencantumkan agen yang dapat diakses	GET	/v1/projects/*/locations/*/dataAgents:listaccessible	Mencantumkan agen data yang dapat diakses dalam project. Agen data dianggap dapat diakses jika pengguna yang memanggil API ini memiliki izin get pada agen. Anda dapat menggunakan kolom creator_filter untuk mengelola agen mana yang ditampilkan oleh metode ini: NONE (default): Menampilkan semua agen data yang dapat diakses oleh pengguna, terlepas dari siapa yang membuat agen tersebut. CREATOR_ONLY: Hanya menampilkan agen data yang dapat diakses oleh pengguna dan yang dibuat oleh pengguna tersebut. NOT_CREATOR_ONLY: Hanya menampilkan agen data yang dapat diakses oleh pengguna dan yang dibuat oleh orang lain.
Menghapus agen	DELETE	/v1/projects/*/locations/*/dataAgents/*	Menghapus agen data.
Menghapus agen secara sinkron	DELETE	/v1/projects/*/locations/*/dataAgents/*:deleteSync	Menghapus agen data secara sinkron.
Membuat percakapan	POST	/v1/projects/*/locations/*/conversations	Memulai percakapan baru yang persisten.
Melakukan percakapan menggunakan referensi percakapan	POST	/v1/projects/*/locations/*:chat	Melanjutkan percakapan stateful dengan mengirimkan pesan chat yang merujuk ke percakapan yang ada dan konteks agen terkait. Untuk percakapan multi-giliran, Google Cloud menyimpan dan mengelola histori percakapan.
Melakukan chat menggunakan referensi agen data	POST	/v1/projects/*/locations/*:chat	Mengirim pesan chat stateless yang merujuk ke agen data tersimpan untuk konteks. Untuk percakapan multi-turn, aplikasi Anda harus mengelola dan menyediakan histori percakapan dengan setiap permintaan.
Melakukan chat menggunakan konteks inline	POST	/v1/projects/*/locations/*:chat	Mengirim pesan chat stateless dengan memberikan semua konteks secara langsung dalam permintaan, tanpa menggunakan agen data tersimpan. Untuk percakapan multi-turn, aplikasi Anda harus mengelola dan menyediakan histori percakapan dengan setiap permintaan.
Mendapatkan percakapan	GET	/v1/projects/*/locations/*/conversations/*	Mengambil detail percakapan tertentu.
Membuat daftar percakapan	GET	/v1/projects/*/locations/*/conversations	Mencantumkan percakapan dalam project tertentu.
Mencantumkan pesan dalam percakapan	GET	/v1/projects/*/locations/*/conversations/*/messages	Mencantumkan pesan dalam percakapan tertentu.
Menghapus percakapan	DELETE	/v1/projects/*/locations/*/conversations/*	Menghapus percakapan tertentu. Peran Identity and Access Management Topic Admin atau setidaknya izin Identity and Access Management cloudaicompanion.topics.delete diperlukan untuk memanggil endpoint ini.
Data kueri	POST	/v1beta/projects/*/locations/*/conversations:queryData	Membuat kueri data dari database AlloyDB, GoogleSQL untuk Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL menggunakan bahasa alami.
Mendapatkan kartu agen (A2A)	GET	/v1/a2a/projects/*/locations/*/agents/*/v1/card	Mengambil kemampuan, keterampilan, dan ekstensi yang didukung untuk agen data bawaan atau kustom menggunakan protokol A2A.
Mengirim pesan (A2A)	POST	/v1/a2a/projects/*/locations/*/agents/*/v1/message:send	Mengirim pesan ke agen data menggunakan protokol A2A.
Mengirim pesan streaming (A2A)	POST	/v1/a2a/projects/*/locations/*/agents/*/v1/message:stream	Mengirim pesan streaming ke agen data menggunakan protokol A2A, yang menampilkan progres penalaran real-time dan artefak terstruktur (seperti kueri SQL dan visualisasi diagram).

Dukungan dan masukan

Untuk mendapatkan bantuan atau melaporkan masalah, hubungi Layanan Pelanggan. Ikuti panduan di Membuat dan mengelola kasus dukungan untuk membuka kasus dukungan Anda. Gunakan panduan berikut saat membuat kasus:

• Untuk mendapatkan dukungan terkait Conversational Analytics API dengan BigQuery, di daftar Select a product, pilih BigQuery, dan di kolom Feature, pilih AI and Machine Learning::Conversational Analytics API in BigQuery.
• Untuk mendapatkan dukungan terkait Conversational Analytics API dengan Looker, di daftar Select a product, pilih Looker (original), dan di kolom Feature, pilih Gemini in Looker::Conversational Analytics API.

Catatan: Dukungan untuk Conversational Analytics API mencakup masalah teknis terkait penggunaan layanan API. Proses debug kode umum dan kustom tidak termasuk dalam cakupan. Pelanggan bertanggung jawab untuk men-debug kode kustom mereka sendiri.

Jika Anda memiliki masukan atau pertanyaan umum tentang Conversational Analytics API, kirim email ke [e-mail]. Kami tidak menjamin respons terhadap komunikasi email, tetapi kami membaca email dan merujuk ke masukan ini selama perencanaan roadmap.

Anda juga dapat mengajukan permintaan fitur untuk fungsionalitas Conversational Analytics API baru.