Agen Data Science Stateful di Agent Engine

1. Ringkasan

Dalam codelab ini, Anda akan membangun agen ilmu data yang mengkueri data real dari set data publik BigQuery dan mengingat preferensi Anda di seluruh sesi. Kemudian, Anda akan men-deploy-nya ke Agent Engine, layanan Google Cloud terkelola sepenuhnya yang menangani infrastruktur, penskalaan, dan pengelolaan sesi.

Agen menggunakan tiga kemampuan inti yang diaktifkan secara progresif:

• BigQuery Toolset: Agen menjelajahi skema dan menjalankan kueri SQL terhadap set data BigQuery yang sebenarnya — hal ini berfungsi baik secara lokal maupun saat di-deploy.
• Bank Memori: Saat di-deploy, agen akan mengingat preferensi dan konteks pengguna di seluruh sesi yang terputus.
• Kemampuan observasi: Cloud Trace merekam langkah-langkah penalaran agen, panggilan alat, dan latensi melalui instrumentasi OpenTelemetry.

Yang akan Anda pelajari

• Cara membuat agen ADK dengan BigQueryToolset untuk akses data sebenarnya
• Cara mengonfigurasi Bank Memori untuk persistensi lintas sesi
• Cara men-deploy agen Anda ke Agent Engine dengan adk deploy
• Cara memberikan izin IAM untuk akun layanan agen yang di-deploy
• Cara menguji persistensi dan kemampuan observasi memori

Yang Anda butuhkan

• Project Google Cloud yang mengaktifkan penagihan
• Google Cloud SDK (CLI gcloud)
• Browser web seperti Chrome
• uv (pengelola paket Python)
• Python 3.12+ (diinstal secara otomatis oleh uv jika diperlukan)

ADK (Agent Development Kit) adalah framework Google untuk membangun agen AI. Codelab ini menggunakan ADK untuk membuat agen dan men-deploy-nya ke Agent Engine.

Codelab ini ditujukan bagi developer tingkat menengah yang sudah memahami Python dan Google Cloud.

Codelab ini membutuhkan waktu sekitar 30 menit untuk diselesaikan (termasuk 5–10 menit untuk deployment).

Resource yang dibuat dalam codelab ini seharusnya berbiaya kurang dari $5.

2. Menyiapkan lingkungan Anda

Buat Project Google Cloud

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.

Menetapkan Variabel Lingkungan

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

Mengaktifkan API

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$GOOGLE_CLOUD_PROJECT

• AI Platform API (aiplatform.googleapis.com) — Hosting Agent Engine
• BigQuery API (bigquery.googleapis.com) — Kueri SQL terhadap set data publik dan pribadi
• Telemetry API (telemetry.googleapis.com) — Pelacakan OpenTelemetry untuk kemampuan observasi agen

Pengaktifan API mungkin memerlukan waktu hingga satu menit untuk diterapkan. Jika Anda melihat error "API not enabled" di langkah-langkah selanjutnya, tunggu sebentar dan coba lagi.

Membuat Lingkungan Virtual dan Menginstal ADK

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install google-adk google-auth

Paket google-adk mencakup alat CLI adk yang akan Anda gunakan untuk menguji dan men-deploy agen.

3. Buat Agen

Buat direktori project agen baru. Semua perintah berikutnya harus dijalankan dari direktori kerja ini (parent dari data_science_agent/):

mkdir data_science_agent

Struktur direktori akhir Anda akan terlihat seperti ini:

./
  data_science_agent/
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step
    .env                # created in the Deploy step

Anda akan membuat __init__.py dan agent.py sekarang, lalu menambahkan requirements.txt dan .env di langkah Deploy.

Buat data_science_agent/__init__.py — file ini diperlukan agar ADK dapat menemukan dan memuat agen Anda:

from . import agent  # noqa: F401 — required by `adk eval` and `adk web`

Buat data_science_agent/agent.py:

Agen ini terhubung ke BigQuery untuk ekstraksi data dan mempertahankan sesi ke Memory Bank.

Memori diaktifkan secara otomatis saat di-deploy — variabel lingkungan GOOGLE_CLOUD_AGENT_ENGINE_ID ditetapkan oleh runtime Agent Engine dan tidak ada saat berjalan secara lokal.

from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App
from google.adk.tools.bigquery import BigQueryCredentialsConfig
from google.adk.tools.bigquery import BigQueryToolset
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Set it with: export GOOGLE_CLOUD_PROJECT=<your-project-id>"
    )

credentials, _ = google.auth.default()
bq_toolset = BigQueryToolset(credentials_config=BigQueryCredentialsConfig(credentials=credentials))

# GOOGLE_CLOUD_AGENT_ENGINE_ID is set automatically by the Agent Engine runtime.
agent_engine_id = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")


async def _save_memory(callback_context: CallbackContext) -> None:
    """Persist the session to Memory Bank after each agent run.

    Only activates on Agent Engine where Memory Bank is available.
    """
    if agent_engine_id:
        await callback_context.add_session_to_memory()


root_agent = LlmAgent(
    name="data_science_agent",
    model="gemini-2.5-pro",
    instruction=(
        "You are an expert Data Science Agent. "
        "Your goal is to query enterprise BigQuery datasets, analyze the data, "
        "and summarize your findings. "
        f"When executing SQL queries, use project_id `{PROJECT_ID}` as the "
        "billing project unless the user specifies a different one. "
        "Present results clearly with formatted numbers. "
        "Remember user preferences like preferred regions, date ranges, "
        "or analysis formats across conversations."
    ),
    tools=[bq_toolset, PreloadMemoryTool()],
    after_agent_callback=_save_memory,
)

app = App(
    name="data_science_agent",
    root_agent=root_agent,
)

Mari kita pelajari fungsi kode ini:

1. BigQueryToolset memberi agen alat seperti execute_sql, list_table_ids, dan get_table_info — agen dapat menjelajahi skema dan membuat kueri set data apa pun yang dapat diakses pemanggil.
2. PreloadMemoryTool otomatis mengambil memori yang relevan sebelum setiap panggilan LLM dengan menelusuri Memory Bank untuk menemukan konten yang terkait dengan pesan pengguna. Callback _save_memory mempertahankan sesi ke Memory Bank setelah setiap kali agen berjalan, sehingga agen dapat mengingat konteks dalam sesi mendatang.
3. App membungkus agen root menjadi aplikasi yang dapat di-deploy yang dapat ditayangkan oleh Agent Engine. name harus cocok dengan nama direktori (data_science_agent) — adk web menggunakannya untuk menemukan dan memuat agen.
4. Petunjuk memberi tahu agen untuk menggunakan project penagihan untuk kueri SQL dan mengingat preferensi pengguna.

4. Men-deploy ke Agent Engine

Buat file requirements.txt di direktori data_science_agent:

google-adk>=1.26.0
google-genai>=1.27.0
google-auth>=2.0.0
python-dotenv>=1.1.0
opentelemetry-instrumentation-fastapi
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk dan google-genai — framework ADK dan klien Gemini
• google-auth — Autentikasi Google Cloud
• python-dotenv — memuat file .env saat memulai
• Empat paket opentelemetry-instrumentation-* memungkinkan fitur pengamatan yang akan Anda pelajari nanti. Mereka menginstrumentasi permintaan HTTP FastAPI, panggilan model Gemini, dan komunikasi gRPC/HTTP internal sehingga rekaman aktivitas muncul di tab Agent Engine Traces.

Jangan tambahkan google-cloud-aiplatform[agent-engines] ke requirements.txt Anda. CLI deployment ADK otomatis menambahkan dependensi ini selama deployment. Mendeklarasikannya kembali dengan versi yang berbeda dapat menyebabkan konflik versi paket OpenTelemetry yang secara diam-diam merusak instrumentasi, sehingga menyebabkan rekaman aktivitas tidak muncul di tab Traces.

Buat file .env di direktori data_science_agent untuk mengaktifkan telemetri pada agen yang di-deploy:

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY — mengaktifkan pipeline OpenTelemetry di runtime Agent Engine.
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT — mencatat input perintah dan respons agen secara lengkap, berguna untuk proses debug.

Setelan OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT mencatat seluruh konten perintah pengguna dan respons agen ke Cloud Logging. Hal ini berguna untuk proses debug, tetapi dapat merekam data sensitif atau PII. Dalam produksi, tetapkan ini ke false atau pastikan Anda telah menerapkan kebijakan penanganan data yang sesuai.

Deploy agen. Argumen terakhir data_science_agent adalah direktori yang berisi kode agen Anda:

adk deploy agent_engine \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --display_name="Data Science Agent" \
  --trace_to_cloud \
  --otel_to_cloud \
  data_science_agent

Bendera	Tujuan
--project / --region	Project dan region Google Cloud target
--display_name	Nama yang mudah dibaca yang ditampilkan di Konsol Cloud
--trace_to_cloud	Mengaktifkan pengekspor Cloud Trace untuk rentang agen
--otel_to_cloud	Mengaktifkan pipeline instrumentasi OpenTelemetry

Deployment biasanya memerlukan waktu 5–10 menit. Setelah selesai, Anda akan melihat: Created agent engine: projects/.../reasoningEngines/

Selagi Anda menunggu, tinjau dokumen Memory Bank untuk mempelajari lebih lanjut cara kerja memori lintas sesi.

URL yang dicetak oleh adk deploy mungkin salah. Jika link tidak berfungsi, buka halaman Agent Engine di Konsol Cloud, lalu klik agen Anda.

Saat di-deploy ke Agent Engine, dua kemampuan akan aktif secara otomatis:

• Memory Bank: PreloadMemoryTool terhubung ke Memory Bank Agent Engine dan _save_memory mempertahankan sesi secara otomatis.
• Kemampuan observasi: Cloud Trace merekam langkah-langkah penalaran, panggilan alat, dan latensi agen.

5. Memberikan Izin BigQuery

Anda harus memberikan akses BigQuery ke akun layanan Agent Engine. Saat di-deploy, agen berjalan sebagai akun layanan yang dikelola Google (bukan kredensial pribadi Anda), sehingga memerlukan izin eksplisit untuk menjalankan kueri SQL.

PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT \
  --format='value(projectNumber)')

SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Required to execute SQL queries
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.dataViewer"

Setiap perintah mencetak Updated IAM policy for project [...] jika berhasil.

Jika Anda melewati langkah ini, agen yang di-deploy akan menampilkan error 403 saat menjalankan kueri SQL. Peran bigquery.jobUser diperlukan di project penagihan (project Anda), bukan project data.

Catatan: bigquery.dataViewer memberikan akses baca ke semua set data dalam project Anda. Untuk penggunaan produksi, sebaiknya berikan peran ini di tingkat set data.

6. Menguji Agen yang Di-deploy

Buka halaman Agent Engine di Konsol Google Cloud. Klik agen yang di-deploy untuk membuka Agent Engine Playground.

Setiap kueri mungkin memerlukan waktu 10–30 detik untuk diselesaikan saat agen melakukan penalaran, memanggil alat, dan menampilkan hasil.

Uji kemampuan BigQuery:

1. "List the tables in bigquery-public-data.hacker_news"
   • Diharapkan: Agen memanggil list_table_ids dan menampilkan nama tabel termasuk full.
2. "Temukan jumlah postingan per tahun di bigquery-public-data.hacker_news.full"
   • Diharapkan: Agen memanggil execute_sql dengan kueri SQL dan menampilkan tabel tahun dan jumlah postingan.
3. "Berapa persentase perubahan postingan year-over-year?"
   • Harapan: Agen memanggil execute_sql dengan kueri SQL yang menghitung perubahan persentase dan menampilkan hasilnya.

7. Menguji Persistensi Memori

Masih di Playground, ajari agen preferensi:

1. "Ingat bahwa set data favorit saya adalah bigquery-public-data.hacker_news"
2. "Apa saja meja yang tersedia?"

Tunggu beberapa detik hingga memori tetap ada (callback _save_memory berjalan setelah agen merespons).

Sekarang mulai sesi baru dengan mengklik tombol "+ Sesi Baru" di sidebar Playground, lalu tanyakan:

3. "Apa set data favorit saya?"

Agen harus mengingat bigquery-public-data.hacker_news meskipun ini adalah sesi baru tanpa histori percakapan. Hal ini berfungsi karena:

• _save_memory akan tetap ada di setiap sesi ke Bank Memori melalui callback_context.add_session_to_memory()
• PreloadMemoryTool mengambil memori yang relevan sebelum setiap panggilan LLM
• Bank Memori mencocokkan konten secara semantik, bukan hanya berdasarkan kata kunci

Jika agen tidak mengingat preferensi Anda, tunggu 10 detik dan coba lagi di sesi baru lainnya. Persistensi memori bersifat asinkron dan mungkin perlu waktu beberapa saat untuk diselesaikan.

8. Menjelajahi Kemampuan Observasi

Di Konsol Cloud, buka agen yang di-deploy, lalu klik tab Traces.

Anda akan melihat Session table yang mencantumkan sesi dari kueri pengujian yang Anda jalankan pada langkah-langkah sebelumnya. Tabel ini menampilkan metrik ringkasan untuk setiap sesi — durasi rata-rata, panggilan model, panggilan alat, penggunaan token, dan error apa pun.

Klik sesi untuk memeriksa detail rekaman aktivitasnya, termasuk:

• Grafik asiklik berarah (DAG) rentangnya — yang menunjukkan perincian langkah demi langkah dari penalaran agen, panggilan alat (kueri BigQuery), dan latensi
• Input dan output untuk setiap rentang (diaktifkan melalui variabel lingkungan OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT di .env)
• Atribut metadata seperti ID rentang, ID pelacakan, dan pengaturan waktu

Anda juga dapat beralih ke tampilan Rentang (tombol di bagian atas) untuk melihat rentang individual di semua sesi.

Perekaman aktivitas mungkin memerlukan waktu 1–2 menit untuk muncul setelah kueri selesai. Jika Anda belum melihat jejak apa pun, tunggu sebentar dan muat ulang halaman.

Cara Kerja Pelacakan

Saat Anda men-deploy dengan --trace_to_cloud dan --otel_to_cloud, runtime Agent Engine akan menginisialisasi pipeline OpenTelemetry yang:

1. Membuat TracerProvider dengan pengekspor OTLP yang mengirim span ke telemetry.googleapis.com
2. Menggunakan empat paket instrumentasi dari requirements.txt Anda untuk merekam rentang dari library utama (FastAPI, Gemini, httpx, gRPC) — google-genai diinstrumentasikan secara eksplisit oleh runtime, sementara yang lain berkontribusi melalui penemuan otomatis OpenTelemetry
3. Mengelompokkan dan mengekspor rentang ke Telemetry API, tempat tab Traces membacanya

Image dasar Agent Engine menyediakan SDK dan eksportir OpenTelemetry, tetapi tidak menyertakan paket instrumentasi. Itulah sebabnya requirements.txt Anda harus mencantumkan keempatnya. Tanpa keempatnya, rentang tidak akan dibuat dan tidak ada rekaman aktivitas yang muncul.

Pemecahan masalah

Jika tidak ada rekaman aktivitas yang muncul setelah beberapa menit:

1. Periksa apakah Telemetry API sudah diaktifkan — Anda mengaktifkannya di langkah penyiapan. Verifikasi dengan: gcloud services list --enabled --project=$GOOGLE_CLOUD_PROJECT | grep telemetry
2. Periksa Cloud Logging untuk melihat peringatan — buka Logging > Logs Explorer dan cari "telemetry enabled but proceeding without". Jika Anda melihat peringatan tentang instrumentasi GenAI, opentelemetry-instrumentation-google-genai tidak ada di requirements.txt Anda.
3. Jangan tambahkan google-cloud-aiplatform[agent-engines] ke requirements.txt Anda. CLI deployment ADK menambahkannya secara otomatis; mendeklarasikannya kembali dengan versi yang berbeda dapat menyebabkan konflik paket OpenTelemetry dan merusak instrumentasi secara diam-diam.

9. Pembersihan

Untuk menghindari tagihan berkelanjutan, hapus resource yang dibuat selama codelab ini.

Hapus agen yang di-deploy dari halaman Agent Engine di Konsol Cloud. Pilih agen Anda, lalu klik Hapus.

Kueri BigQuery dalam codelab ini menggunakan set data publik, yang tidak menimbulkan biaya penyimpanan. Peran IAM yang Anda berikan tetap ada di project, tetapi tidak berdampak pada biaya.

Jika Anda membuat project khusus untuk codelab ini, Anda dapat menghapus seluruh project tersebut:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Secara opsional, bersihkan lingkungan lokal Anda:

deactivate
rm -rf .venv data_science_agent

10. Selamat

Anda telah membuat agen ilmu data stateful dan men-deploy-nya ke Agent Engine.

Yang telah Anda pelajari

• Cara membuat agen ADK dengan BigQueryToolset untuk akses data sebenarnya
• Cara mengaktifkan memori persisten dengan Memory Bank menggunakan PreloadMemoryTool dan after_agent_callback
• Cara memberikan izin IAM untuk akun layanan agen yang di-deploy
• Cara men-deploy ke Agent Engine dan mengaktifkan kemampuan observasi dengan Cloud Trace

Langkah berikutnya

• Membuat kueri set data BigQuery pribadi Anda sendiri dengan memberikan akses akun layanan Agent Engine ke data Anda
• Menambahkan Eksekusi Kode untuk menjalankan analisis Python di sandbox yang aman
• Siapkan dasbor kemampuan observasi Cloud Trace untuk memantau agen Anda dalam produksi
• Memublikasikan hasil ke Google Workspace menggunakan alat MCP

Dokumen referensi

• Dokumentasi ADK
• Dokumentasi Agent Engine
• Dokumentasi Memory Bank
• Panduan Deployment Agent Engine