Mendukung Sistem Agentic Anda dengan HTAP di AlloyDB

1. Ringkasan

Di Bagian 1, kita berhasil mengubah PDF yang kacau dan tidak terstruktur menjadi tabel yang bersih, cerdas, dan terstruktur di BigQuery menggunakan Knowledge Catalog dan DataScan. Sekarang, kita memiliki data warehouse yang kuat. Di Bagian 2, kita menyiapkan AlloyDB sebagai tulang punggung transaksional dan menggabungkan tabel BigQuery ke dalamnya, sehingga membuat lapisan data terpadu tanpa menduplikasi satu byte pun.

Hari ini, kita akan membangun otak. Kita akan membuat aplikasi Multi-Agen — "FroyoOS Store Manager" — yang berada di atas lapisan data ini untuk menjawab pertanyaan, memeriksa alergen, dan memproses pesanan langsung.

Tantangan: Memisahkan AI dari Agen Anda

Saat membangun Agen AI yang perlu berkomunikasi dengan database, anti-pola yang paling umum adalah memaksa data dan logika AI langsung ke dalam aplikasi Python Anda. Hal ini membuat aplikasi Anda rentan, tidak aman, dan sangat sulit dipertahankan seiring pertumbuhan arsitektur data Anda.

Untuk mengatasi hal ini, kita akan menggunakan MCP (Model Context Protocol) Toolbox. MCP Toolbox bertindak sebagai lapisan abstraksi data terpadu kita. Kita akan menentukan operasi database secara deklaratif dalam file tools.yaml sederhana. Kita akan men-deploy toolbox ini sebagai endpoint serverless yang aman di Google Cloud Run. Agen AI kita cukup terhubung ke endpoint ini dan mengatakan, "Jalankan alat 'place_order'."

***Penting: Jika Anda belum menyelesaikan bagian 2, sekarang adalah waktu yang tepat untuk melakukannya. Kita memiliki beberapa data yang dibuat di bagian tersebut dan digunakan di aplikasi ini.

Kekuatan HTAP

Sebelum kita mulai membangun agen, mari kita bahas alasan judul postingan ini secara khusus menyebutkan HTAP (Hybrid Transactional/Analytical Processing).

Dalam arsitektur tradisional, jika Agen AI perlu memproses pesanan pengguna langsung (beban kerja OLTP transaksional) dan melakukan referensi silang terhadap ribuan pemetaan bahan yang kompleks (beban kerja OLAP analitis), aplikasi Python Anda harus mengelola koneksi ke dua database yang sama sekali berbeda. Hal ini akan menyebabkan latensi yang parah, overhead keamanan, dan pengelolaan status yang rentan.

Kita mengubah AlloyDB menjadi pusat HTAP dengan menggabungkan data warehouse BigQuery secara native langsung ke PostgreSQL. Karena arsitektur HTAP ini, Agen AI kita saat ini hanya perlu berkomunikasi dengan satu endpoint database. Agen AI dapat menyisipkan transaksi langsung ke dalam tabel live_orders dan menjalankan pemindaian analitis yang berat terhadap set data froyo_data BigQuery gabungan dalam satu waktu, tanpa menduplikasi satu byte data pun. Mari kita lihat cara mengekspos mesin ini ke AI kita.

Mulai membuat.

Yang akan Anda pelajari

• Cara menyiapkan Cluster, Instance, dan Jaringan AlloyDB dengan sekali klik
• Cara menyiapkan ekstensi untuk mempersiapkan gabungan
• Cara menyiapkan gabungan dari BigQuery ke AlloyDB
• Melakukan pengujian

Persyaratan

• Browser, seperti Chrome atau Firefox.
• Project Google Cloud yang mengaktifkan penagihan.
• Pengetahuan dasar tentang SQL.

2. Sebelum memulai

Membuat project

1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Ada fitur terbatas di lab ini yang dapat Anda coba meskipun tanpa akun penagihan. Jika Anda ingin mencoba langsung fitur tersebut, Anda memiliki catatan yang berlaku dan tercakup dalam kualifikasi "TIDAK PUNYA AKUN PENAGIHAN?". Perhatikan catatan tersebut.

3. Anda akan menggunakan Cloud Shell, lingkungan command line yang berjalan di Google Cloud. Klik Aktifkan Cloud Shell di bagian atas konsol Google Cloud.

4. Setelah terhubung ke Cloud Shell, Anda dapat memeriksa apakah Anda sudah diautentikasi dan project sudah ditetapkan ke project ID Anda menggunakan perintah berikut:

gcloud auth list

5. Jalankan perintah berikut di Cloud Shell untuk mengonfirmasi bahwa perintah gcloud mengetahui project Anda.

gcloud config list project

6. Jika Anda ingin melakukan autentikasi

gcloud auth login

7. Jika project Anda belum ditetapkan, gunakan perintah berikut untuk menetapkannya:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project <YOUR_PROJECT_ID>

8. Aktifkan API yang diperlukan: Jalankan perintah ini untuk mengaktifkan semua API yang diperlukan:

gcloud services enable \
  alloydb.googleapis.com \
  bigquery.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  artifactregistry.googleapis.com \
  iam.googleapis.com \
  secretmanager.googleapis.com \
  compute.googleapis.com \
  servicenetworking.googleapis.com

Hal yang Perlu Diperhatikan &Pemecahan Masalah

Sindrom "Project Hantu"	Anda menjalankan gcloud config set project, tetapi sebenarnya Anda melihat project lain di UI Konsol. Periksa project ID di dropdown kiri atas!
Hambatan Penagihan	Anda mengaktifkan project, tetapi lupa akun penagihan. AlloyDB adalah mesin berperforma tinggi; mesin ini tidak akan dimulai jika "tangki bahan bakar" (penagihan) kosong.
Penundaan Penyebaran API	Anda mengklik "Aktifkan API", tetapi command line masih menampilkan Service Not Enabled. Tunggu selama 60 detik. Cloud memerlukan waktu untuk mengaktifkan neuronnya.
Kekacauan Kuota	Jika Anda menggunakan akun uji coba baru, Anda mungkin mencapai kuota regional untuk instance AlloyDB. Jika us-central1 gagal, coba us-east1.

3. Menyiapkan Data

Pastikan data terstruktur yang kita ekstrak dari PDF tidak terstruktur tersedia di BigQuery dan gabungan data BigQuery AlloyDB juga telah dibuat dan diuji. Jika Anda belum menyelesaikan langkah-langkah tersebut, sekarang adalah waktu yang tepat untuk membuka dan menjalankan langkah-langkah sederhana tersebut dari sini dan sini untuk bagian 1 dan 2.

Catatan:

Jika Anda mencoba codelab ini, Anda tidak boleh menjalankan langkah pembersihan bagian 2 (menghapus langkah cluster dan instance) karena kita memerlukan orkestrasi AlloyDB untuk sistem agen kita yang ditunjukkan di sini.

Selain data yang telah kita buat di bagian 2, kita perlu membuat satu tabel tambahan di instance AlloyDB. Buka AlloyDB Studio menggunakan link berikut:

https://console.cloud.google.com/alloydb/locations/us-central1/clusters/my-alloydb-cluster/studio

Ubah nama cluster di link di atas jika Anda menggunakan cluster yang berbeda.

Di AlloyDB Studio, di tab Query Editor baru, jalankan pernyataan berikut:

CREATE TABLE live_orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100),
    product_id VARCHAR(100),
    quantity INT,
    order_status VARCHAR(50) DEFAULT 'Pending',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Tindakan ini akan membuat tabel live_orders di database Anda.

4. Menentukan Abstraksi (tools.yaml)

Pertama, kita akan mendaftarkan operasi database secara formal. Kita akan membuat file tools.yaml yang menentukan cara agen kita berinteraksi dengan AlloyDB yang memiliki data transaksional dan analitis (data analitis dari gabungan BigQuery).

1. Buka Terminal Cloud Shell. Beralih ke mode Editor.
2. Buat folder baru di direktori root Anda: "froyo-agent"
3. Di dalam folder, buat file tools.yaml dan tempelkan konten berikut: (ganti dengan nilai Anda sendiri untuk project, cluster, instance, dan sandi)

# tools.yaml
sources:
    alloydb-source:
        kind: "alloydb-postgres"
        project: "*******"
        region: "us-central1"
        cluster: "my-alloydb-cluster"
        instance: "my-primary-inst"
        database: "postgres"
        user: "postgres"
        password: "*******"
        ipType: "private"


tools:
  check_allergens:
    kind: postgres-sql
    source: alloydb-source
    description: Queries the federated BigQuery tables to find allergens for a product.
    statement: |
      SELECT a.allergen_name
      FROM consistsof c
      INNER JOIN product p ON c.product_id = p.product_id
      INNER JOIN ingredient i ON c.ingredient_id = i.ingredient_name
      INNER JOIN containsallergen a ON i.ingredient_id = a.ingredient_id
      WHERE UPPER(p.product_name) LIKE UPPER($1)
    parameters:
      - name: product_name
        type: string
        description: The name of the product to check. (e.g., '%Midnight%')


  place_order:
    kind: postgres-sql
    source: alloydb-source
    description: Inserts a new live transaction into the native AlloyDB orders table.
    statement: |
      INSERT INTO live_orders (customer_name, product_id, quantity)
      VALUES ($1, (SELECT product_id FROM product WHERE product_name ILIKE '%' || $2 || '%' LIMIT 1), $3) RETURNING order_id;
    parameters:
      - name: customer_name
        type: string
        description: The name of the customer placing the order.
      - name: product_name
        type: string
        description: The name of the product being ordered.
      - name: quantity
        type: integer
        description: The quantity of the product being ordered.


toolsets:
  alloydb_tools:
    - check_allergens
    - place_order

Kita telah membatasi kemampuan agen kita menjadi 2 alat — memeriksa alergen dan melakukan pemesanan.

5. Men-deploy Toolbox ke Cloud Run

Agar tersedia untuk aplikasi kita, kita akan men-deploy toolbox dengan aman menggunakan gcloud CLI. Tindakan ini akan membuat endpoint lapisan abstraksi kita.

4. Beralih ke Terminal Cloud Shell, dan buka direktori kerja dengan menjalankan perintah:

cd froyo-agent

5. Simpan tools.yaml dalam secret bernama "tools-froyo":

gcloud secrets create tools-froyo --data-file=tools.yaml

6. Deploy container MCP Toolbox ke Cloud Run

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest

gcloud run deploy toolbox-froyo \
    --image $IMAGE \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools-froyo:latest" \
    --args="--config=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --network easy-alloydb-vpc \
    --subnet easy-alloydb-subnet \
    --allow-unauthenticated \
    --vpc-egress private-ranges-only

Nilai "network" dan "subnet" harus diganti jika Anda menggunakan nilai yang berbeda dari yang kita konfigurasi di codelab Bagian 2.

7. Catat URL Cloud Run yang dihasilkan (misalnya, https://toolbox-froyo-xxx.run.app).

Kita akan menggunakan endpoint MCP Toolbox yang di-deploy ini pada langkah konfigurasi agen.

6. Backend Agen (app.py)

Dengan database yang diabstraksi, kode Python kita dapat berfokus sepenuhnya pada orkestrasi dan penalaran.

Kita akan menggunakan Agent Development Kit (ADK) bersama Flask. ADK menyediakan memori sesi tingkat perusahaan (InMemorySessionService), yang berarti agen kita mengingat konteks percakapan. ADK terintegrasi secara native dengan ToolboxSyncClient untuk mengambil alat kita dengan lancar dari Cloud Run.

Berikut app.py:

https://github.com/AbiramiSukumaran/froyo-data/blob/main/app.py

Aplikasi Python Flask sederhana menghubungkan agen ADK ke alat yang telah kita tentukan di Toolbox yang pada gilirannya berinteraksi dengan AlloyDB (dan data gabungan BigQuery juga) serta merespons pengguna.

Untuk mendapatkan project ini di Cloud Shell Editor, Anda dapat meng-clone repositori untuk agen dengan menjalankan perintah berikut dari Cloud Shell Terminal:

cd

git clone https://github.com/AbiramiSukumaran/froyo-data

Anda akan melihat struktur project berikut:

TIDAK PUNYA AKUN PENAGIHAN?

Jika Anda membaca codelab ini secara sekilas, mencoba langsung, tetapi tidak terlalu mendalam tanpa akun penagihan, Anda mungkin tidak dapat menyiapkan tugas DataScan atau melakukan inferensi Knowledge Catalog atau gabungan AlloyDB. Atau Anda melewatkan codelab 1 &2, jadi berikut data yang tersedia untuk Anda sehingga Anda dapat mencoba arsitektur dan aplikasi:

Bagian di bawah akan membantu Anda terus mencoba data:

TIDAK PUNYA AKUN PENAGIHAN?

Langkah-langkah untuk terus mencoba data tanpa akun penagihan:

1. File data berikut tersedia di repo untuk memudahkan:
2. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.allergen.csv
3. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.consistsof.csv
4. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.containsallergen.csv
5. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.froyo_data_materialized.csv
6. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.ingredient.csv
7. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.product.csv
8. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.suppliedby.csv
9. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.supplier.csv

File ini harus ada di folder yang sama dengan app.py.

B. File Python bernama app-nobill.py di jalur yang sama

1. Di folder root project, ada file bernama app-nobill.py
2. File ini dirancang untuk membuat pengalaman aplikasi yang sama, tetapi tanpa perlu terhubung secara eksplisit ke sumber data ini karena data telah tersedia dalam file.
3. Semua file lainnya seperti yang disebutkan di lab harus tetap ada untuk versi ini juga (hanya tidak perlu menjalankan file app.py)

7. UI dan Menjalankan Aplikasi

Untuk memberikan pengalaman yang tepat kepada Store Manager kita, kita membuat UI glassmorphic yang elegan (templates/index.html) yang menampilkan sidebar katalog produk langsung dan antarmuka chat interaktif.

Anda dapat menemukan index.html di file repo di sini:

https://github.com/AbiramiSukumaran/froyo-data/blob/main/templates/index.html

Sebelum menjalankan aplikasi, pastikan Anda memiliki dependensi di file requirements.txt dengan konten berikut:

Flask>=3.0.0
google-genai>=0.1.0
mcp>=1.0.0
google-adk
toolbox-core
toolbox-langchain
python-dotenv

dan file .env Anda terisi:

GOOGLE_API_KEY=***
MCP_TOOLBOX_SERVER_URL=***

Bagaimana cara mendapatkan GOOGLE_API_KEY ?

Ikuti petunjuk di blog ini untuk menyiapkan Kunci API Google Anda.

Bagaimana cara mendapatkan MCP_TOOLBOX_SERVER_URL?

Kita menyiapkan hal ini pada langkah sebelumnya di codelab ini dan Anda menyalin endpoint MCP Toolbox yang di-deploy. Gunakan link tersebut untuk variabel lingkungan MCP_TOOLBOX_SERVER_URL.

Jalankan aplikasi Anda:

Dari Cloud Shell Terminal, pastikan Anda berada di folder project, jalankan perintah berikut satu per satu:

Buka folder root project:

cd froyo-data

Instal dependensi:

pip install -r requirements.txt

Menjalankan file python:

python app.py

TIDAK PUNYA AKUN PENAGIHAN?

Dalam hal ini, bukan menjalankan file python app.py, jalankan perintah berikut:

python app-nobill.py

TIDAK PUNYA AKUN PENAGIHAN?

Klik link yang muncul di terminal atau buka http://localhost:8080.

8. Pengujian Lengkap

Mari kita klik produk dari katalog untuk bertanya kepada agen:

Does Midnight Swirl have any allergens?

Anda akan melihat respons berikut:

Video di balik layar:

1. Agen ADK menerima perintah dan memutuskan untuk menggunakan alat check_allergens.
2. Agen ADK memanggil MCP Toolbox di Cloud Run dengan aman.
3. Toolbox menjalankan kueri di AlloyDB, yang langsung digabungkan ke BigQuery untuk memindai hubungan kompleks yang kita buat di Bagian 1.
4. Database menampilkan "Soy", yang dirangkum dengan rapi oleh Agen di UI.

Selanjutnya, kita akan mengatakan:

Order 2 Midnight Swirl for Alice.

Agen meneruskan string "Midnight Swirl" ke Toolbox. SQL yang mendasarinya akan menyelesaikan string secara dinamis ke ID bilangan bulat melalui BigQuery, menyisipkan pesanan langsung ke AlloyDB, dan mengonfirmasi transaksi.

Repo Kode

https://github.com/AbiramiSukumaran/froyo-data

9. Pembersihan

Setelah lab ini selesai, jangan lupa untuk menghapus cluster dan instance AlloyDB.

Buka https://console.cloud.google.com/alloydb/clusters. Pilih cluster yang ingin Anda hapus dengan mengklik elipsis vertikal di sampingnya, lalu klik HAPUS.

Tindakan ini akan membersihkan cluster beserta instance-nya.

10. Selamat atas Agen Anda!

Pikirkan hal yang baru saja kita capai:

Sistem agen kita yang terorkestrasi dengan baik hanya berinteraksi dengan MCP Toolbox untuk database. Di balik layar, sistem ini menangani panggilan alat dan logika data ke AI aplikasi kita, sehingga alurnya tetap sederhana:

1. Aplikasi transaksional kita (yang berjalan di AlloyDB) dapat menangani sesi pengguna yang cepat dan serentak.
2. Jika memerlukan data analitis yang berat atau konteks historis (seperti detail supplier atau pemetaan bahan yang kompleks), aplikasi akan membuat kueri froyo_dataschema BigQuery.
3. Nol ETL. Tidak ada pipeline data yang rusak. Tidak ada database yang tidak sinkron. Kita menyimpan data sekali (di BQ) dan melakukan komputasi saat kita membutuhkannya.

Setelah fondasi agen &data kita — baik analitis maupun transaksional — selesai, mari kita lanjutkan ke bagian berikutnya.

Apa Selanjutnya?

Agen kita berfungsi dengan sempurna... di jalur yang benar. Di Bagian 4, kita akan membangun pipeline Evaluasi Agen untuk menguji validitas, dasar, dan performa sistem agen kita secara ketat. Sampai jumpa!