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 aplikasi Python Anda. Hal ini membuat aplikasi Anda rentan, tidak aman, dan sangat sulit dipertahankan seiring pertumbuhan arsitektur data Anda.

Untuk mengatasinya, kita akan menggunakan MCP (Model Context Protocol) Toolbox. MCP Toolbox bertindak sebagai lapisan abstraksi data terpadu. 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 dalam aplikasi ini.

Kekuatan HTAP

Sebelum kita mulai membangun agen, mari kita bahas mengapa 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 memasukkan transaksi langsung ke tabel live_orders dan menjalankan pemindaian analitis yang berat terhadap set data BigQuery froyo_data gabungan dalam satu waktu, tanpa menduplikasi satu byte data pun. Mari kita lihat cara mengekspos mesin ini ke AI kita.

Mulai membangun.

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.
• Pemahaman dasar mengenai 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 diaktifkan di 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 yang tercakup dalam kualifikasi "TIDAK ADA AKUN PENAGIHAN?". Perhatikan hal tersebut.

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

4. Setelah terhubung ke Cloud Shell, Anda dapat memeriksa apakah Anda sudah diautentikasi dan project 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!
Penghalang 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. Mempersiapkan Data

Pastikan data terstruktur yang kita ekstrak dari PDF tidak terstruktur tersedia di BigQuery dan gabungan data BigQuery AlloyDB juga 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 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:

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 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 utama 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 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 secara 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).

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.

TIDAK ADA AKUN PENAGIHAN?

Jika Anda membaca codelab ini secara sekilas, langsung, tetapi tingkat tinggi 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:

Langkah-langkah untuk terus mencoba data dengan akun penagihan:

A.Di folder utama project Anda, download file ini dari repo:

1. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.allergen.csv
2. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.consistsof.csv
3. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.containsallergen.csv
4. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.froyo_data_materialized.csv
5. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.ingredient.csv
6. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.product.csv
7. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.suppliedby.csv
8. https://github.com/AbiramiSukumaran/froyo-data/blob/main/froyo_data.supplier.csv

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

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

1. Di folder utama project, buat file bernama app-nobill.py dan salin konten dari: https://github.com/AbiramiSukumaran/froyo-data/blob/main/app-nobill.py

C. Semua file lainnya seperti yang disebutkan di lab harus tetap ada untuk versi ini juga (hanya tidak perlu menjalankan file app.py)

TIDAK ADA AKUN PENAGIHAN?

7. UI dan Menjalankan Aplikasi

Untuk memberikan pengalaman yang tepat kepada Store Manager, kita membuat UI glassmorphic yang rapi (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 telah menginstal dependensi dengan membuat 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 diisi:

GOOGLE_API_KEY=***
MCP_TOOLBOX_SERVER_URL=***

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

Instal dependensi:

pip install -r requirements.txt

Menjalankan file python:

python app.py

TIDAK ADA AKUN PENAGIHAN?

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

python app-nobill.py

TIDAK ADA AKUN PENAGIHAN?

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

8. Pengujian Terbaik

Mari kita klik produk dari katalog untuk bertanya kepada agen:

Does Midnight Swirl have any allergens?

Anda akan melihat respons:

Di balik layar:

1. Agen ADK menerima perintah dan memutuskan untuk menggunakan alat check_allergens.
2. Agen ADK memanggil MCP Toolbox di Cloud Run secara 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 Swirls for Alice.

Agen meneruskan string "Midnight Swirl" ke Toolbox. SQL yang mendasarinya secara dinamis menyelesaikan string ke ID bilangan bulat melalui BigQuery, memasukkan 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 apa 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 data ke logika 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 sekali (di BQ) dan melakukan komputasi di tempat yang kita butuhkan.

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

Langkah Berikutnya

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!