Conversational Analytics API: Membuat agen data dan melakukan chat dengan data Anda

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

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, untuk membangun antarmuka chat yang didukung teknologi kecerdasan buatan (AI), atau agen data, yang menggunakan bahasa alami untuk menjawab pertanyaan tentang data terstruktur di BigQuery, Looker, dan Looker Studio. 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 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, Gemini untuk produk Google Cloud dapat menghasilkan output yang seolah masuk akal, tetapi mengandung fakta yang salah. Sebaiknya Anda memvalidasi semua output dari Gemini untuk Google Cloud produk sebelum Anda menggunakannya. Untuk mengetahui informasi selengkapnya, lihat Gemini untuk Google Cloud dan responsible AI.

Catatan: Penawaran Pratinjau Pra-GA (1) ditujukan untuk digunakan di lingkungan pengujian saja dan tidak boleh digunakan di lingkungan produksi atau untuk memproses data pribadi atau data lain yang tunduk pada persyaratan kepatuhan hukum atau peraturan, dan (2) tunduk pada Persyaratan Penawaran Pra-GA dalam Persyaratan Khusus Layanan, dan Lampiran Izin untuk Gemini dalam Google Cloud Program Penguji Tepercaya.

Mulai menggunakan Conversational Analytics API

Untuk mulai menggunakan Conversational Analytics API, Anda dapat meninjau dokumentasi arsitektur dan konsep utama terlebih dahulu untuk memahami cara agen memproses permintaan, alur kerja untuk pembuat dan pengguna agen, mode percakapan, serta peran Pengelolaan Identitas dan Akses (IAM). Kemudian, untuk mulai membuat agen data, Anda dapat memilih antara pengalaman terpandu dengan panduan memulai, codelab, notebook, Agent Development Kit (ADK) dan MCP Toolbox, atau pendekatan mandiri dengan mengikuti langkah-langkah di Penyiapan dan prasyarat.

Panduan Memulai

Gunakan aplikasi Panduan memulai Streamlit untuk berintegrasi dengan Conversational Analytics API di lingkungan pengujian lokal.

Codelab

Ikuti tutorial langkah demi langkah untuk mempelajari cara menggunakan Python SDK dengan data BigQuery menggunakan Conversational Analytics API Codelab.

Notebook

Gunakan notebook Colaboratory Conversational Analytics API berikut untuk pengalaman terpandu yang akan membantu Anda memulai Conversational Analytics API:

• Notebook Colaboratory HTTP: Memberikan panduan langkah demi langkah yang interaktif untuk menyiapkan lingkungan, membuat agen data, dan melakukan panggilan API menggunakan permintaan HTTP.
• Notebook Colaboratory Python SDK: Memberikan panduan langkah demi langkah yang interaktif untuk menyiapkan lingkungan, membuat agen data, dan melakukan panggilan API menggunakan Python SDK.

Agent Development Kit (ADK) dan MCP Toolbox

Pelajari cara menggunakan fungsi ask_data_insights di Agent Development Kit (ADK) untuk menjawab pertanyaan tentang data Anda dalam bahasa alami.

Tinjau demo dan alat Conversational Analytics yang menunjukkan kemampuan Conversational Analytics API dan memberikan pola integrasi praktis.

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 Conversational Analytics API dengan IAM: Menjelaskan cara menggunakan Identity and Access Management untuk membagikan dan mengelola akses ke agen data.
• Mengautentikasi dan menghubungkan ke sumber data dengan Conversational Analytics API: Memberikan petunjuk untuk mengautentikasi API dan mengonfigurasi koneksi ke data BigQuery, Looker, dan Looker Studio Anda.

Membangun dan berinteraksi dengan agen data

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

• Membangun agen data menggunakan HTTP: Memberikan contoh lengkap tentang cara membangun dan berinteraksi dengan agen data menggunakan permintaan HTTP langsung dengan Python.
• Membangun agen data menggunakan Python SDK: Memberikan contoh lengkap tentang cara membangun dan berinteraksi dengan agen data menggunakan Python SDK.
• Memandu perilaku agen dengan konteks yang dibuat: Pelajari cara memberikan konteks yang dibuat untuk memandu perilaku agen dan meningkatkan akurasi respons. Anda juga dapat melihat contoh konteks yang dibuat 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.

Praktik terbaik

Tinjau panduan berikut untuk mempelajari praktik terbaik penggunaan Conversational Analytics API:

• Mengelola biaya BigQuery untuk agen Anda: Pelajari cara memantau dan mengelola biaya BigQuery untuk agen Conversational Analytics API dengan menetapkan batas pembelanjaan tingkat project, tingkat pengguna, dan tingkat kueri.
• Ajukan pertanyaan yang efektif: Pelajari cara membuat pertanyaan yang efektif bagi agen Anda untuk mendapatkan hasil maksimal dari Conversational Analytics API.
• Memecahkan masalah error Conversational Analytics API: Memecahkan masalah error umum Conversational Analytics API.
• Batasan umum: Memberikan informasi mendetail tentang batasan umum Conversational Analytics API, termasuk batasan kueri, data, visualisasi, dan pertanyaan.

Operasi API utama

API ini menyediakan endpoint inti berikut untuk mengelola agen data dan percakapan:

Operasi	Metode HTTP	Endpoint	Deskripsi
Buat agen	POST	/v1beta/projects/*/locations/*/dataAgents	Membuat agen data baru.
Mendapatkan agen	GET	/v1beta/projects/*/locations/*/dataAgents/*	Mengambil detail agen data tertentu.
Mendapatkan kebijakan Identity and Access Management	POST	/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy	Mendapatkan izin Pengelolaan Akses dan Identitas yang ditetapkan untuk setiap pengguna pada agen data tertentu. Pengguna dengan peran Pemilik Agen Data dapat memanggil endpoint ini untuk melihat kebijakan Pengelolaan Akses dan Identitas agen data sebelum menggunakan endpoint setIAMpolicy untuk membagikan agen data kepada pengguna lain.
Menetapkan kebijakan Identity and Access Management	POST	/v1beta/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 Pengelolaan Akses dan Identitas pengguna tersebut.
Memperbarui agen	PATCH	/v1beta/projects/*/locations/*/dataAgents/*	Mengubah agen data yang ada.
Mencantumkan agen	GET	/v1beta/projects/*/locations/*/dataAgents	Mencantumkan agen data yang tersedia dalam project.
Mencantumkan agen yang dapat diakses	GET	/v1beta/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. 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	/v1beta/projects/*/locations/*/dataAgents/*	Menghapus agen data.
Buat percakapan	POST	/v1beta/projects/*/locations/*/conversations	Memulai percakapan baru yang persisten.
Memulai percakapan dengan menggunakan referensi percakapan	POST	/v1beta/projects/*/locations/*:chat	Melanjutkan percakapan stateful dengan mengirim pesan chat yang mereferensikan percakapan yang ada dan konteks agen terkait. Untuk percakapan bolak-balik, Google Cloud menyimpan dan mengelola histori percakapan.
Melakukan chat menggunakan referensi agen data	POST	/v1beta/projects/*/locations/*:chat	Mengirim pesan chat tanpa status yang mereferensikan agen data tersimpan untuk konteks. Untuk percakapan multi-turn, aplikasi Anda harus mengelola dan menyediakan histori percakapan dengan setiap permintaan.
Memulai percakapan dengan menggunakan konteks inline	POST	/v1beta/projects/*/locations/*:chat	Mengirim pesan chat stateless dengan memberikan semua konteks 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	/v1beta/projects/*/locations/*/conversations/*	Mengambil detail percakapan tertentu.
Membuat daftar percakapan	GET	/v1beta/projects/*/locations/*/conversations	Mencantumkan percakapan dalam project tertentu.
Mencantumkan pesan dalam percakapan	GET	/v1beta/projects/*/locations/*/conversations/*/messages	Mencantumkan pesan dalam percakapan tertentu.
Menghapus percakapan	DELETE	/v1beta/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.

Kirim masukan

Gunakan link berikut untuk melaporkan bug atau meminta fitur.

• Mengajukan laporan bug
• Mengajukan permintaan fitur

Referensi lainnya

Referensi REST API Analytics Percakapan memberikan deskripsi mendetail tentang metode, endpoint, dan definisi jenis untuk struktur permintaan dan respons.