Pola integrasi untuk agen data

Halaman ini menjelaskan pola integrasi untuk menyematkan pengalaman agen data ke dalam aplikasi Anda. Pola ini bervariasi dalam kompleksitas, mulai dari komponen chat tersemat hingga sistem multi-agen yang diorkestrasi.

Panduan ini ditujukan bagi cloud architect dan data engineer yang mendesain aplikasi AI generatif. Anda harus memiliki pemahaman dasar tentang konsep Google Cloud , Identity and Access Management (IAM), dan REST API. Anda juga harus memahami arsitektur sumber data yang digunakan aplikasi Anda.

Ringkasan pola integrasi

Panduan ini disusun dalam jalur utama berikut, yang masing-masing didasarkan pada titik awal Anda:

  • Jalur Looker: Pilih jalur ini jika Anda ingin menyediakan fungsi chat melalui penyematan Looker, Looker API, atau Analisis Percakapan API.
  • BigQuery and database track: Pilih jalur ini jika Anda membangun aplikasi kustom yang menggunakan BigQuery, Data Studio, atau database operasional yang didukung.

Tabel berikut merangkum pola integrasi yang tersedia:

Pola integrasi Deskripsi Sumber data
Penyematan iframe Looker Menambahkan antarmuka percakapan standar ke aplikasi yang memerlukan kode minimal. Looker
Looker API dan SDK Membangun antarmuka chat kustom yang menggunakan Looker API untuk autentikasi. Looker
Analisis Percakapan API (sumber Looker) Mengelola agen data Looker sebagai resource Google Cloud yang berfungsi di berbagai platform dan sistem multi-agen. Looker
Direct API (agen tunggal) Menggunakan integrasi API langsung untuk alur teks ke jawaban. BigQuery, database, Looker
API langsung (orkestrator) Merutekan kueri antara API dan alat lainnya menggunakan panggilan fungsi. BigQuery, database, Looker
ADK (berbasis skema) dengan BigQueryToolset Menghasilkan insight cepat dari referensi tabel menggunakan alat ask_data_insights. BigQuery
ADK (diatur) dengan DataAgentToolset Membuat kueri agen data yang telah dikonfigurasi sebelumnya dan menggunakan alat ask_data_agent untuk memastikan perilaku yang konsisten. BigQuery, database, Looker
ADK (streaming kustom) Mendukung streaming diagram dan SQL secara real-time menggunakan class agen kustom. BigQuery, database, Looker
MCP dengan McpToolset atau ToolboxToolset Menghubungkan aplikasi ke alat data yang menggunakan Model Context Protocol (MCP). BigQuery, Looker
Server MCP jarak jauh Analisis Percakapan API Menyediakan gateway aman terpadu yang memungkinkan agen root di platform AI pihak ketiga dan platform yang dikelola Google (seperti Gemini Enterprise) menemukan dan berkomunikasi dengan agen data khusus di seluruh Google Cloud. BigQuery, database, Looker
A2A protocol Memungkinkan kolaborasi yang aman antara agen khusus yang beroperasi di berbagai sistem. Bergantung pada framework

Opsi integrasi untuk Looker

Jika menggunakan Looker, Anda dapat menyediakan Looker Conversational Analytics kepada pengguna melalui pola berikut:

Ringkasan pola integrasi Looker

Tabel berikut merangkum pola integrasi utama untuk Looker:

Pola Paling cocok untuk Kelebihan Pertimbangan
Menyematkan dengan iframe: Metode low-code untuk menambahkan pengalaman chat Looker standar ke aplikasi dengan cepat. Tim yang memerlukan pengalaman Analisis Percakapan siap produksi dengan pengembangan kustom minimal.
  • Memerlukan kode minimal untuk diterapkan.
  • Otomatis menerapkan model keamanan Looker yang ada.
  • Tidak memerlukan autentikasi Google Cloud terpisah.
  • Mendukung Looker Embed SDK, yang mempercepat pengembangan dengan mengelola siklus proses iframe dan penerusan peristiwa.
  • Menawarkan penyesuaian UI terbatas dan bergantung pada antarmuka pengguna chat Looker standar.
  • Instance Looker Anda harus dihosting oleh Looker.
Membangun dengan Looker API dan SDK: Pendekatan fleksibel untuk membangun antarmuka chat kustom sekaligus mempertahankan autentikasi dan pengelolaan agen dalam Looker. Tim yang memerlukan pengalaman pengguna chat kustom, tetapi ingin mempertahankan autentikasi pengguna dan pengelolaan agen dalam ekosistem Looker. Pola ini ideal untuk aplikasi yang sudah menggunakan penyematan atau API Looker.
  • Menyediakan satu lapisan autentikasi dan kontrol penuh atas antarmuka pengguna.
  • Menyederhanakan arsitektur untuk pelanggan Looker yang sudah ada.
  • Menggunakan lapisan semantik Looker untuk meningkatkan akurasi kueri.
  • Tidak memerlukan autentikasi Google Cloud terpisah.
  • Memerlukan keahlian pengembangan Looker API.
  • Terbatas untuk sumber data Looker.
  • Agen dikelola dalam Looker dan tidak dapat dipindahkan ke layanan Google Cloud lain.
Menggunakan Conversational Analytics API: Integrasi langsung dengan API untuk mengelola agen sebagai resource tingkat cloud. Pelanggan Looker yang memerlukan portabilitas lintas platform untuk agen data mereka.
  • Memastikan bahwa agen data dapat dipindahkan di semua platform Google Cloud .
  • Diatur secara terpusat oleh IAM.
  • Memungkinkan Anda mengintegrasikan agen data ke dalam alur kerja ADK atau MCP.
  • Mengharuskan Anda mengelola stack integrasi lengkap, termasuk autentikasi Google Cloud dan Looker.
  • Agen data dikelola secara independen dari antarmuka pengguna Looker.

Menyematkan dengan iframe

Anda dapat menyematkan Analisis Percakapan sebagai iframe untuk memberikan pengalaman chat di luar UI Looker. Pola ini adalah cara langsung untuk menyediakan Analisis Percakapan yang tidak memerlukan pengembangan UI kustom, orkestrasi backend, atau pengelolaan status API. Untuk menggunakan pola ini, tambahkan URL yang telah diformat ke dalam aplikasi Anda.

Embed SDK Looker menyediakan alat yang mengelola tugas seperti pembuatan URL yang aman, pengelolaan siklus proses iframe, dan penerusan peristiwa JavaScript antara aplikasi host dan iframe. Anda dapat menyematkan halaman Agen, halaman Percakapan, atau percakapan tertentu dengan menambahkan URL yang telah diformat ke dalam aplikasi Anda.

Anda dapat menggunakan metode autentikasi berikut untuk konten tersemat:

  • Penyematan pribadi: Mengautentikasi pengguna dengan kredensial Looker yang ada. Saat Anda menetapkan URL sematan sebagai sumber iframe, pengguna akan login dengan akun Looker mereka. Metode ini otomatis menerapkan peran, akses konten, dan izin tingkat data yang ada, seperti filter akses atau pemberian akses, tanpa memerlukan konfigurasi IAM atau pemetaan token tambahan.
  • Penyematan bertanda tangan: Mengautentikasi pengguna melalui aplikasi Anda menggunakan single sign-on (SSO). Anda membuat URL bertanda tangan yang menyertakan jalur konten Analisis Percakapan, yang memungkinkan Anda menentukan secara dinamis izin yang akan diberikan.

Membangun dengan Looker API dan SDK

Untuk fleksibilitas lebih dalam pengalaman chat, Anda dapat menggunakan metode ConversationalAnalytics di Looker API atau menggunakan Looker SDK untuk membangun aplikasi kustom. Pendekatan ini memungkinkan Anda membangun frontend kustom yang berkomunikasi langsung dengan endpoint Looker.

Integrasi dengan Looker API memberikan manfaat berikut:

  • Anda hanya mengelola autentikasi dengan Looker. Anda tidak perlu melakukan autentikasi secara terpisah dengan Conversational Analytics API.
  • Untuk aplikasi yang sudah menggunakan penyematan Looker atau API, pola ini menyederhanakan arsitektur project dengan menghindari mekanisme autentikasi sekunder dan menghilangkan kebutuhan untuk mengelola agen data eksternal.
  • Anda memiliki kontrol penuh atas antarmuka chat, alur percakapan, dan cara aplikasi merender hasil (seperti diagram dan tabel).

Untuk mengetahui implementasi referensi, lihat panduan Looker API yang menggunakan metode ConversationalAnalytics di GitHub.

Menggunakan Conversational Analytics API dengan data Looker

Anda dapat berintegrasi langsung dengan Analisis Percakapan API di geminidataanalytics.googleapis.com jika perlu melakukan salah satu tugas berikut:

  • Bagikan agen data yang sama di beberapa platform Google Cloud , seperti aplikasi web kustom, Google Chat, dan Gemini Enterprise.
  • Gabungkan sumber data Looker dengan sumber database operasional atau BigQuery dalam satu sistem multi-agen.
  • Kelola agen data Anda sebagai resource tingkat cloud yang diatur oleh IAM, bukan model izin Looker.

Untuk mengetahui informasi selengkapnya tentang pola arsitektur umum untuk Conversational Analytics API, lihat Opsi integrasi untuk BigQuery dan database.

Opsi integrasi untuk BigQuery, Data Studio, dan database

Bagian ini menjelaskan pola arsitektur untuk aplikasi yang menggunakan BigQuery, Data Studio, atau database operasional Google Cloud yang didukung untuk membangun pengalaman kustom dengan Conversational Analytics API.

Jika Anda menggunakan Analisis Percakapan API dengan sumber data Looker, pola yang dijelaskan di bagian ini juga berlaku untuk integrasi Anda.

API Analisis Percakapan menyediakan metode utama berikut untuk berinteraksi dengan data:

  • Metode chat: Mendukung BigQuery, Looker, Data Studio, dan database operasional.
  • Metode queryData: Mendukung database operasional seperti AlloyDB, GoogleSQL untuk Spanner, Cloud SQL untuk MySQL, dan Cloud SQL untuk PostgreSQL.

Saat membuat aplikasi kustom, Anda dapat menggunakan satu atau beberapa pola integrasi berikut:

  • Integrasi API langsung: Pendekatan kustom yang memberikan fleksibilitas paling tinggi, tetapi mengharuskan Anda membangun infrastruktur untuk autentikasi, pengelolaan percakapan, dan penguraian respons.
  • Orkestrasi berbasis framework (ADK): Pendekatan yang menggunakan Agent Development Kit (ADK) untuk perutean multi-agen, eksekusi alat, dan pengelolaan status.
  • Integrasi vertikal (MCP): Pendekatan yang menggunakan Model Context Protocol (MCP) untuk menyediakan cara yang seragam dalam menghubungkan aplikasi AI ke alat dan sumber data di berbagai lingkungan.
  • Orkestrasi horizontal (A2A): Pendekatan yang menggunakan protokol Agent-to-Agent (A2A) untuk memungkinkan agen khusus di berbagai sistem berkolaborasi dengan aman tanpa memerlukan kode integrasi kustom.

Ringkasan pola integrasi BigQuery dan database

Tabel berikut merangkum pola implementasi spesifik untuk BigQuery dan database operasional:

Pola Paling cocok untuk Kelebihan Pertimbangan
Integrasi agen tunggal (API langsung): Pola saat aplikasi Anda memanggil API secara langsung untuk menampilkan insight dari sumber data Anda. Aplikasi, prototipe, atau microservice agen tunggal yang memerlukan kontrol langsung atas setiap panggilan API.
  • Memberikan kontrol terperinci tanpa dependensi framework.
  • Menyediakan arsitektur paling sederhana untuk kasus penggunaan agen tunggal.
  • Mendukung mode stateful dan stateless.
  • Mengharuskan Anda membangun semua infrastruktur untuk autentikasi, pengelolaan status, penguraian respons, penanganan error, streaming, dan deployment.
  • Tidak dapat diskalakan dengan baik untuk skenario multi-agen.
Orchestrator kustom (API langsung): Pola yang menggunakan agen root dan pemanggilan fungsi untuk merutekan kueri antara Analisis Percakapan API dan alat atau layanan lainnya. Aplikasi yang menggabungkan kueri data dengan tugas lain, seperti email atau dokumen, dalam satu alur percakapan.
  • Memberikan kontrol orkestrasi maksimum tanpa dependensi framework.
  • Memungkinkan Anda menentukan dengan tepat cara model merutekan antar-alat.
  • Berfungsi dengan model Gemini apa pun.
  • Mengharuskan Anda mengelola definisi alat, loop percakapan, status multi-giliran, penanganan error, dan deployment secara manual.
  • Overhead pengembangan mungkin menjadi beban dibandingkan dengan menggunakan framework seperti ADK.
Integrasi berbasis skema dengan BigQueryToolset (ADK): Pola yang menggunakan referensi tabel untuk menampilkan insight data dengan cepat. Pembuatan prototipe cepat, alat internal yang tata kelola datanya kurang penting, atau skenario yang insight datanya merupakan salah satu dari beberapa kemampuan dalam agen ADK.
  • Menyediakan jalur integrasi tercepat dalam framework ADK.
  • Tidak memerlukan pra-konfigurasi agen data.
  • Bekerja langsung dengan nama tabel database.
  • Tidak memiliki tata kelola semantik dan menghasilkan SQL hanya dari inferensi skema.
  • Beroperasi dalam mode stateless di level API.
  • Memberikan jawaban hanya teks dan tidak mendukung diagram.
Integrasi yang diatur dengan DataAgentToolset (ADK): Pola yang mengkueri agen data yang telah dikonfigurasi sebelumnya dengan merujuk ke ID agen. Aplikasi produksi yang memerlukan akses data yang konsisten atau sistem multi-agen yang menggunakan agen data sebagai komponen tepercaya yang dapat digunakan kembali.
  • Menyediakan tata kelola semantik dan perilaku yang konsisten di semua konsumen.
  • Meningkatkan akurasi dengan menggunakan kueri terverifikasi dan glosarium bisnis.
  • Memastikan bahwa agen data dapat digunakan kembali di seluruh integrasi ADK, MCP, dan API langsung.
  • Mengharuskan Anda mengonfigurasi resource agen data terlebih dahulu.
  • Beroperasi dalam mode stateless di level API.
  • Menampilkan jawaban khusus teks dan tidak mendukung diagram.
Sub-agen kustom (ADK): Pola yang menggunakan class agen kustom untuk terhubung langsung ke API dan melakukan streaming potongan data kembali ke pengguna. Aplikasi yang ditampilkan kepada pengguna dengan latensi respons rendah sebagai prioritas atau pipeline multi-agen dengan pengambilan data yang mendukung agen downstream.
  • Memberikan masukan streaming real-time.
  • Mengakses semua jenis respons, seperti diagram, tabel, dan SQL.
  • Dapat dikomposisikan dengan agen ADK lain melalui status sesi.
  • Memerlukan lebih banyak upaya pengembangan untuk membangun class agen ADK kustom.
  • Mengharuskan Anda mengelola koneksi streaming dan penguraian respons secara langsung.
Model Context Protocol (MCP): Pola yang menggunakan standar terbuka untuk menghubungkan aplikasi AI ke sumber data dan alat di berbagai lingkungan. Organisasi yang memerlukan interoperabilitas alat di beberapa klien AI dan IDE, atau tim yang memerlukan alat data yang sama agar dapat diakses dari framework ADK, IDE, dan aplikasi kustom.
  • Menggunakan standar alat universal yang berfungsi dengan klien yang mematuhi MCP.
  • Memisahkan implementasi alat dari aplikasi konsumen.
  • Menawarkan opsi server terkelola, seperti server Google Cloud MCP.
  • Memerlukan lapisan infrastruktur tambahan untuk server toolbox.
  • Menyediakan integrasi yang lebih longgar daripada toolset ADK.
  • Bergantung pada ekosistem MCP Toolbox yang terus berkembang.
  • Beroperasi dalam mode stateless yang mengharuskan Anda mengelola status multi-turn secara eksternal.
Agent-to-Agent (A2A): Pola yang menggunakan protokol A2A, standar terbuka yang memungkinkan agen khusus di berbagai sistem berkolaborasi dengan aman tanpa memerlukan kode integrasi kustom. Lingkungan perusahaan yang sangat terdistribusi, tempat agen perutean pusat harus mendelegasikan tugas ke agen data yang beroperasi di berbagai sistem atau jaringan.
  • Mengurangi kebutuhan akan kode integrasi kustom antara framework yang berbeda.
  • Memastikan interoperabilitas lintas platform yang lancar.
  • Menyediakan penemuan kemampuan yang aman dan terstandardisasi.
  • Menimbulkan latensi jaringan kecil dibandingkan dengan sub-agen internal.
  • Mengharuskan Anda mengonfigurasi setelan server A2A.

Integrasi API langsung

Integrasi API langsung memberikan kontrol terperinci atas logika dan arsitektur aplikasi Anda, tetapi mengharuskan Anda membangun infrastruktur pendukung. Dengan pendekatan ini, Anda bertanggung jawab atas tugas-tugas seperti autentikasi, pengelolaan percakapan, penguraian respons, dan deployment.

Bagian ini membahas topik berikut:

  • Integrasi agen tunggal: Pola saat aplikasi Anda memanggil API Analisis Percakapan secara langsung untuk menampilkan Insight dari sumber data Anda.
  • Integrasi orchestrator kustom: Pola lanjutan yang menggunakan agen root dan pemanggilan fungsi untuk merutekan kueri antara API Analisis Percakapan.

Integrasi agen tunggal

Dengan integrasi agen tunggal, backend Anda langsung memanggil Conversational Analytics API menggunakan REST atau library klien dan meneruskan kueri serta konteks pengguna. Pola ini cocok untuk aplikasi dengan kompleksitas rendah, seperti aplikasi web, alat chat internal, atau microservice, yang menggunakan alur teks-ke-jawaban yang sederhana. Anda juga dapat menggunakan pendekatan ini untuk pembuatan prototipe dan pekerjaan bukti konsep.

Pola ini mendukung chat stateful, tempat Google mengelola histori percakapan, dan chat stateless, tempat aplikasi Anda mengelola histori.

Untuk mengetahui implementasi referensi, lihat panduan memulai Analisis Percakapan API atau demo emas Analisis Percakapan API di GitHub.

Integrasi orchestrator kustom

Dengan pendekatan ini, Anda membangun agen root yang bertindak sebagai titik entri dan koordinator utama untuk aplikasi Anda. Agen root menggunakan model Gemini standar yang dilengkapi dengan alat melalui panggilan fungsi. Saat pengguna mengajukan pertanyaan terkait data, agen root akan memancarkan panggilan alat ke API Analisis Percakapan, menerima hasilnya, lalu dapat melanjutkan penalaran atau memanggil alat lain di downstream.

Pemanggilan fungsi melibatkan tahap-tahap berikut:

  1. Deklarasikan: Tentukan skema alat sebagai objek FunctionDeclaration yang menyertakan definisi parameter.
  2. Memanggil: Model menampilkan pesan functionCall terstruktur yang berisi nama dan argumen fungsi.
  3. Execute: Aplikasi Anda melakukan panggilan API dan menampilkan hasilnya dalam pesan FunctionResponse.
  4. Sintesis: Model Gemini menggunakan hasil tersebut untuk menghasilkan jawaban akhir atau menentukan tindakan berikutnya.

Pendekatan ini cocok untuk aplikasi yang penggunanya mungkin meminta insight data bersama dengan tugas lainnya. Misalnya, pengguna mungkin meminta agen untuk "Tampilkan penjualan, lalu buat draf email untuk tim penjualan". Agen root dapat mengarahkan pertanyaan data ke Conversational Analytics API dan menggunakan alat lain untuk tugas non-data.

Untuk mengetahui implementasi referensi, lihat halaman orchestrate atau multimodal di demo emas Analisis Percakapan API di GitHub.

Orkestrasi berbasis framework (ADK)

Agent Development Kit (ADK) adalah framework berbasis kode untuk membangun agen AI yang mengelola kompleksitas pemilihan rute multi-agen, eksekusi alat, dan pengelolaan status. Framework ADK adalah framework yang sama dengan yang mendukung Gemini Enterprise.

Dengan menggunakan ADK, Anda dapat merangkai Conversational Analytics API dengan alat dan agen lain untuk melakukan tindakan yang kompleks.

Bagian ini membahas topik berikut:

Integrasi berbasis skema dengan BigQueryToolset

Toolset BigQueryToolset dalam framework ADK menyertakan alat ask_data_insights bawaan. Untuk menggunakan alat ini, Anda meneruskan nama tabel dan pertanyaan pengguna ke alat, yang kemudian memanggil API Analisis Percakapan menggunakan konteks inline.

Saat Anda memanggil alat ini, alat ini akan mengirimkan permintaan stateless yang menyertakan referensi tabel BigQuery yang ditentukan ke Conversational Analytics API. API ini menyimpulkan skema database, membuat dan menjalankan kueri SQL, serta menampilkan jawaban teks. Hasilnya kemudian diteruskan kembali ke agen ADK sebagai respons alat.

Pola ini adalah cara yang efektif untuk menambahkan analisis percakapan ke agen dengan cepat. Namun, karena panggilan ke API bersifat stateless dan tidak memiliki tata kelola, API akan menghasilkan SQL yang sepenuhnya didasarkan pada skema tabel tanpa guardrail semantik. Pola ini lebih cepat di-deploy, tetapi lebih berisiko untuk logika bisnis produksi yang menerapkan konvensi penamaan, logika bisnis, atau kontrol akses.

Integrasi yang diatur dengan DataAgentToolset

Toolset DataAgentToolset dalam framework ADK menyediakan integrasi bawaan yang mereferensikan agen data yang telah dikonfigurasi sebelumnya berdasarkan ID-nya. Agen ADK meneruskan pertanyaan pengguna ke alat ask_data_agent, yang memanggil Analisis Percakapan API dengan konteks agen data yang ditentukan.

Anda dapat membuat agen data secara terprogram menggunakan Conversational Analytics API atau melalui Agent Catalog di konsol Google Cloud . Agen data dilengkapi dengan komponen berikut:

  • Sumber pengetahuan: Tabel, tampilan, atau fungsi yang ditentukan pengguna (UDF) yang dapat dikueri oleh agen
  • Konteks terstruktur: Deskripsi untuk tabel dan kolom yang membantu agen memahami data yang mendasarinya
  • Petunjuk: Panduan tambahan bagi agen untuk menafsirkan dan mengkueri sumber data
  • Kueri terverifikasi: Kueri SQL yang telah divalidasi sebelumnya yang berfungsi sebagai contoh untuk pertanyaan umum
  • Glosarium: Definisi istilah bisnis yang membantu agen memahami bahasa khusus domain

Untuk panduan mendalam tentang cara membuat agen melalui Katalog Agen, lihat codelab analisis percakapan di BigQuery.

Karena agen didefinisikan sebagai unit yang diatur, agen ini menggunakan logika, konteks, dan guardrail tepercaya yang sama, terlepas dari aplikasi atau sub-agen mana yang memanggilnya.

Integrasi UX lanjutan dengan sub-agen kustom

Toolset BigQueryToolset dan DataAgentToolset tidak menampilkan hasil kepada pengguna hingga permintaan API selesai diproses. Karena framework ADK memperlakukan API sebagai alat yang memblokir respons hingga selesai, kueri yang berjalan lebih lama mungkin membuat pengguna tidak mendapatkan masukan.

Sebagai alternatif untuk aplikasi yang memprioritaskan latensi respons rendah atau yang pengambilan datanya digunakan oleh agen downstream, Anda dapat membangun class agen ADK kustom yang terhubung langsung ke API Analisis Percakapan dan melakukan streaming data secara asinkron dalam bentuk potongan-potongan kembali ke pengguna. Pola ini mendukung jenis respons berikut saat dihasilkan:

  • Pesan pemikiran: Proses penalaran agen data saat menafsirkan pertanyaan.
  • Pesan progres: Pembaruan status selama pengambilan data untuk sumber data.
  • Pembuatan kueri: Kueri SQL atau Looker yang dihasilkan, yang di-streaming saat dibuat.
  • Data: Hasil data dalam format JSON.
  • Visualization: Spesifikasi diagram Vega-Lite.
  • Ringkasan: Jawaban akhir berbasis teks.

Untuk mengetahui daftar lengkap jenis data yang ditampilkan, lihat jenis SystemMessage dalam dokumentasi referensi API.

Pendekatan asinkron ini memastikan bahwa pengguna tidak perlu menunggu proses pengambilan data yang kompleks selesai sepenuhnya. Saat mengalir melalui proses kueri, agen data terus membagikan update inkremental—seperti ringkasan teks, data mentah, atau konfigurasi diagram—ke ruang kerja bersama sementara. Data ini kemudian dapat dirender untuk pengguna secara real time dan dibagikan kepada sub-agen khusus untuk melakukan tugas tambahan.

Untuk implementasi referensi yang mencakup agen root, sub-agen data, dan agen visualisasi, lihat demo streaming ADK di GitHub.

Integrasi vertikal (MCP)

Model Context Protocol (MCP) adalah standar terbuka yang menyediakan cara seragam bagi aplikasi AI untuk terhubung ke alat dan sumber data eksternal. MCP menstandarkan antarmuka antara model AI dan alat yang digunakan.

Bagian ini membahas topik berikut:

Server MCP jarak jauh Analisis Percakapan API

Conversational Analytics API menyediakan server MCP jarak jauh di https://geminidataanalytics.googleapis.com/mcp, yang didukung oleh server MCP terkelola Google. Gateway ini menyediakan antarmuka HTTP dan Server-Sent Events (SSE) yang terpadu dan aman, yang memungkinkan agen root di platform AI pihak ketiga dan platform yang dikelola Google (seperti Gemini Enterprise) menemukan dan berkomunikasi dengan agen data khusus di seluruh Google Cloud.

Ringkasan komunikasi agen root

Komunikasi antara agen root eksternal atau yang dikelola Google dan Conversational Analytics API melibatkan tiga peran yang berbeda:

  1. Operator data membuat dan mengonfigurasi agen data tercakup di seluruh platform analisis percakapan, menulis deskripsi yang jelas tentang sumber data yang dapat diakses oleh setiap agen dan pertanyaan yang dapat dijawabnya, serta membagikan agen tersebut kepada pengguna bisnis.
  2. Administrator platform mendaftarkan koneksi MCP kustom di platform agentic mereka yang mengarah ke endpoint https://geminidataanalytics.googleapis.com/mcp. Administrator mengonfigurasi kredensial klien OAuth 2.0 (client ID dan rahasia klien) menggunakan endpoint otorisasi Google (https://accounts.google.com/o/oauth2/v2/auth), endpoint token (https://oauth2.googleapis.com/token), dan cakupan otorisasi yang diperlukan (https://www.googleapis.com/auth/geminidataanalytics dan https://www.googleapis.com/auth/bigquery.readonly).
  3. Pengguna bisnis mengajukan pertanyaan dalam bahasa alami di platform agentic. Alih-alih mengkueri database mentah secara langsung, agen root platform (LLM orchestrator) berkomunikasi dengan server MCP jarak jauh Analisis Percakapan API untuk menemukan agen data yang relevan, mengarahkan pertanyaan pengguna ke agen data yang dicakup dengan tepat, dan menampilkan jawaban yang disintesis.
Propagasi identitas

Untuk mempertahankan tata kelola data perusahaan saat permintaan berasal dari agen root pihak ketiga atau eksternal, server MCP jarak jauh menerapkan propagasi identitas end-to-end:

  • Autentikasi yang didelegasikan pengguna: Saat pengguna bisnis berinteraksi dengan agen root, platform agentic mengautentikasi pengguna melalui alur OAuth 2.0 3-legged dan menyertakan token akses OAuth yang didelegasikan pengguna di header HTTP permintaan yang dikirim ke gateway MCP.
  • Penerusan kredensial pengguna akhir (EUC): Server MCP jarak jauh memvalidasi token dan menyebarkan kredensial pengguna akhir melalui lapisan API Analisis Percakapan ke mesin data yang mendasarinya, seperti BigQuery, Spanner, AlloyDB, dan Cloud SQL.
  • Akses data yang diatur: Karena kueri dijalankan menggunakan identitas pengguna yang diautentikasi, bukan akun layanan bersama, sumber data yang mendasarinya akan otomatis menerapkan izin IAM yang ada, kebijakan keamanan tingkat baris dan tingkat kolom, serta batas akses data yang diatur. Pengguna hanya dapat menemukan agen data dan membuat kueri set data yang aksesnya telah mereka miliki.
  • Model dua identitas Looker: Untuk BigQuery dan database operasional, kueri dijalankan berdasarkan kredensial Google OAuth yang diteruskan milik masing-masing pengguna. Untuk agen data yang didukung Looker, autentikasi menggunakan model dua identitas: token OAuth Google pengguna mengizinkan akses ke agen data di Google IAM, tetapi kueri dijalankan di Looker menggunakan kredensial yang disediakan untuk pengguna Looker API (diteruskan di blok kredensial alat chat). Akses model, izin, dan aturan tingkat baris Looker mencerminkan pengguna API yang dikonfigurasi, bukan identitas Looker pengguna akhir individual.
Cara agen root mengakses metode API

Saat klien MCP terhubung ke https://geminidataanalytics.googleapis.com/mcp, klien tersebut akan memanggil metode tools/list MCP standar untuk mengimpor skema alat yang diekspos oleh API Analisis Percakapan secara dinamis. Agen root kemudian berinteraksi dengan Conversational Analytics API dengan memanggil alat dan resource MCP ini, yang dipetakan langsung ke metode REST API yang mendasarinya:

Alat atau resource MCP Metode API Analisis Percakapan yang dipetakan Cara agen root menggunakannya
list_data_agents projects.locations.dataAgents.list

Menemukan agen data yang tersedia. Agen root meneruskan PROJECT_ID (dan LOCATION) target dan menerima daftar agen data aktif yang diizinkan untuk diakses pengguna, termasuk ID dan deskripsi setiap agen. Agen root mengevaluasi deskripsi ini untuk menentukan agen data mana yang dapat menjawab pertanyaan pengguna.

Tips: Sertakan PROJECT_ID target dalam petunjuk sistem kustom agen root agar agen root tidak meminta pengguna bisnis memberikan project ID.

get_data_agent

(atau resource MCP gda://agents/AGENT_ID)

 projects.locations.dataAgents.get

Memeriksa metadata dan konteks agen data tertentu. Agen root meneruskan AGENT_ID target untuk mengambil detail konfigurasi—seperti tabel BigQuery yang terhubung, petunjuk sistem, glosarium, atau kueri terverifikasi—saat deskripsi agen saja tidak cukup untuk merutekan perintah yang kompleks.
chat projects.locations.chat

Bertindak sebagai proxy eksekusi untuk kueri percakapan. Untuk mengkueri agen data yang ditemukan, agen root meneruskan data_agent_context yang berisi nama resource lengkap agen (projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID) dan pesan bahasa alami pengguna di messages. Untuk kueri ad-hoc stateless, agen root dapat meneruskan inline_context. Alat ini menampilkan jawaban dalam bahasa alami, kueri SQL yang dihasilkan, baris hasil, spesifikasi diagram Vega-Lite, dan penalaran agen.

MCP Toolbox for Databases

Anda juga dapat mengakses Analisis Percakapan API melalui server MCP Toolbox for Databases open source. Server ini menyediakan alat bawaan yang kompatibel dengan MCP yang mengekspos metode chat di Conversational Analytics API:

MCP adalah lapisan interoperabilitas yang mengekspos kemampuan analisis sebagai alat ke klien yang kompatibel dengan MCP, bukan model eksekusi terpisah dari Conversational Analytics API.

Pola implementasi MCP untuk arsitektur mandiri dan ADK

Anda dapat menerapkan MCP melalui pola berikut:

Pola Detail
MCP Mandiri (tanpa ADK)

Menggunakan server MCP Toolbox for Databases sebagai server mandiri untuk terhubung ke klien yang mematuhi MCP. Pola ini umum digunakan untuk tugas-tugas berikut:

  • Integrasi IDE: Hubungkan IDE—seperti Antigravity, Cursor, atau VS Code—ke server untuk mengkueri data secara percakapan dari editor.
  • Klien MCP kustom: Membangun aplikasi yang menggunakan server untuk menyediakan antarmuka alat yang seragam di beberapa penyedia AI.
  • Gemini CLI: Gunakan CLI sebagai klien MCP untuk percakapan data berbasis terminal.
MCP dalam ADK

Framework ADK menyediakan mekanisme berikut untuk mengintegrasikan server MCP ke dalam alur kerja agen:

  • ToolboxToolset: Varian khusus untuk server MCP Toolbox for Databases yang mendukung beberapa metode autentikasi.
  • McpToolset: Menghubungkan agen ADK ke server MCP mana pun menggunakan koneksi server MCP lokal atau jarak jauh. Secara otomatis menemukan alat server dan mengeksposnya ke agen.

Anda juga dapat membangun server MCP menggunakan framework FastMCP untuk mengekspos alat yang dibangun dengan framework ADK ke klien mana pun yang kompatibel dengan MCP. Dengan pendekatan ini, agen ADK Anda tersedia sebagai alat di ekosistem lain.

Pilih pola integrasi yang memenuhi persyaratan arsitektur spesifik aplikasi Anda:

  • Penggunaan toolset Agent Development Kit (ADK) bawaan, seperti BigQueryToolset atau DataAgentToolset, memberikan integrasi yang lebih erat tanpa dependensi server eksternal. Pendekatan ini ideal untuk sistem yang sepenuhnya ada dalam framework ADK.
  • Menggunakan alat di MCP Toolbox memberikan interoperabilitas di seluruh klien yang mematuhi MCP. Pendekatan ini ideal untuk alat data yang harus melayani beberapa aplikasi konsumen atau IDE pihak ketiga.

Orkestrasi horizontal (A2A)

Protokol Agent-to-Agent (A2A) adalah standar terbuka yang memungkinkan agen khusus di berbagai sistem berkomunikasi dan berkolaborasi dengan aman tanpa memerlukan kode integrasi kustom.

Seiring dengan penskalaan sistem, organisasi sering kali men-deploy beberapa agen khusus yang dibangun di berbagai framework atau infrastruktur cloud. A2A membuat tingkat pesan universal untuk agen otonom ini. Alih-alih menggunakan API kustom, setiap agen memublikasikan kartu agen, yang merupakan profil yang dapat ditemukan dan menjelaskan kemampuan agen, format data yang didukung, dan persyaratan keamanan.

Saat orchestrator pusat atau agen peer memerlukan data analisis, agen tersebut mendelegasikan tugas dengan aman ke agen data melalui pesan A2A terstruktur. Agen data memproses permintaan secara otonom dan menampilkan temuan, yang memisahkan logika eksekusi dari pemohon.

Untuk mempelajari cara menemukan kartu agen, mengirim pesan, dan menstreaming artefak terstruktur menggunakan protokol A2A, lihat Mengorkestrasi agen data dengan A2A.

Memilih pola integrasi

Gunakan tabel berikut untuk membandingkan kompleksitas, tata kelola, dan kemampuan setiap pola integrasi.

Tingkat kompleksitas didefinisikan sebagai berikut:

  • Rendah: Pola yang memerlukan kode kustom minimal dan mengandalkan antarmuka pengguna atau alat bawaan.
  • Sedang: Pola yang memerlukan pengembangan frontend kustom dan integrasi API atau SDK, tetapi menghindari infrastruktur orkestrasi backend yang kompleks.
  • Tinggi: Pola yang memerlukan pengembangan aplikasi full-stack, pengelolaan status percakapan, beberapa lapisan autentikasi, atau infrastruktur orchestrator perantara.
  • Bervariasi: Pola yang kompleksitasnya bergantung pada metode integrasi dasar yang Anda pilih.
Pola integrasi Kompleksitas Penyesuaian Tata kelola agen Kontrol akses Multi-agen Streaming Portabilitas
Penyematan iframe Looker Rendah Rendah Dikelola melalui Looker Looker Tidak Bawaan Khusus Looker
Looker API dan SDK Sedang Tinggi Dikelola melalui Looker Looker Tidak Bawaan Khusus Looker
Analisis Percakapan API dengan sumber Looker Bervariasi Tinggi Dikelola melalui API Looker dan IAM Ya Ya Platform Google Cloud apa pun
Agen tunggal (API langsung) Sedang Tinggi Dikelola melalui API IAM Tidak Ya (didukung) Platform Google Cloud apa pun
Orchestrator kustom Tinggi Sangat tinggi Dikelola melalui API IAM Manual Manual Platform Google Cloud apa pun
Berbasis skema dengan BigQueryToolset (ADK) Rendah Sedang Tidak ada (inferensi skema) IAM Ya (ADK) Tidak (memblokir) Ekosistem ADK
Dikelola dengan DataAgentToolset (ADK) Rendah Sedang Dikelola melalui API IAM Ya (ADK) Tidak (memblokir) Ekosistem ADK
Sub-agen streaming kustom (ADK) Tinggi Sangat tinggi Dikelola melalui API IAM Ya (ADK) Ya (kustom) Ekosistem ADK
MCP Mandiri Sedang Sedang Tidak ada (inferensi skema) IAM Tidak Tidak Klien MCP apa pun
MCP dalam ADK Sedang Tinggi Tidak ada (inferensi skema) IAM Ya (ADK) Tidak Klien ADK dan MCP
A2A Protocol Tinggi Tinggi Bergantung pada framework IAM Ya Ya Lintas platform

Langkah berikutnya