Agen Data Science Stateful di Agent Runtime

1. Ringkasan

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

Agen menggunakan tiga kemampuan inti yang diaktifkan secara progresif:

• Toolset BigQuery: Agen menjelajahi skema dan menjalankan kueri SQL terhadap set data BigQuery yang sebenarnya — hal ini berfungsi baik secara lokal maupun saat di-deploy.
• Memory Bank: 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 nyata
• Cara mengonfigurasi Memory Bank untuk persistensi lintas sesi
• Cara men-deploy agen Anda ke Agent Runtime 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
• Browser web seperti Chrome
• Jika Anda menjalankan kode di komputer Anda sendiri, bukan di Cloud Shell: Google Cloud SDK (CLI gcloud), uv (pengelola paket Python), dan 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 Runtime.

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

Codelab ini membutuhkan waktu sekitar 35 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 project Anda

Buka Cloud Shell Editor di project GCP yang Anda buat.

Kemudian, buat Terminal > New Terminal, dan jalankan perintah berikut untuk menyetel project Anda. Perintah selanjutnya akan membaca project ID dari setelan ini.

gcloud config set project <INSERT_YOUR_GCP_PROJECT_HERE>

Mengaktifkan API

Di terminal, jalankan perintah berikut.

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$(gcloud config get project)

• aiplatform.googleapis.com: menghosting agen Anda di Agent Runtime, termasuk Sesi Gemini Enterprise dan Memory Bank, serta menayangkan model Gemini
• BigQuery API (bigquery.googleapis.com): Kueri SQL terhadap set data publik dan pribadi
• Telemetry API (telemetry.googleapis.com): Pelacakan OpenTelemetry untuk observabilitas 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.

Instal ADK

Di terminal, jalankan perintah berikut untuk membuat folder codelab ini dan menginstal ADK serta dependensinya:

mkdir -p ~/adk-deploy-scale
cd ~/adk-deploy-scale
uv init --bare
uv add google-adk google-auth google-cloud-bigquery "google-cloud-aiplatform[agent_engines]"

uv membuat lingkungan Python yang terisolasi untuk codelab ini, jadi Anda tidak perlu mengaktifkan apa pun. Awali perintah Python dengan uv run.

Paket google-adk mencakup alat CLI adk yang akan Anda gunakan untuk menguji dan men-deploy agen. adk deploy menggunakan google-cloud-aiplatform untuk membuat agen Anda di Agent Runtime, dan google-cloud-bigquery adalah library klien di balik alat BigQuery ADK.

3. Buat Agen

Di folder ~/adk-deploy-scale, buat direktori agen. Jalankan semua perintah berikutnya dari ~/adk-deploy-scale (parent dari data_science_agent/):

mkdir data_science_agent

Kemudian, jalankan perintah berikut untuk membuat data_science_agent/.env dengan project Anda, region tempat Anda akan men-deploy agen, dan setelan untuk agen yang di-deploy. adk deploy membaca file ini, sehingga setelan ini tetap berfungsi jika Anda membuka terminal baru.

cat > ~/adk-deploy-scale/data_science_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_ENTERPRISE=True
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
EOF

• GOOGLE_CLOUD_PROJECT dan GOOGLE_CLOUD_LOCATION: project ID Anda (diisi dari gcloud) dan region tempat agen berjalan
• GOOGLE_GENAI_USE_ENTERPRISE: memiliki ADK yang memanggil Gemini melalui project Google Cloud Anda
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: mencatat input perintah lengkap dan respons agen, 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.

Struktur direktori akhir Anda akan terlihat seperti ini:

adk-deploy-scale/
  data_science_agent/
    .env
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step

Anda akan membuat __init__.py dan agent.py sekarang, lalu menambahkan requirements.txt 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. Agent Runtime menetapkan variabel lingkungan GOOGLE_CLOUD_AGENT_ENGINE_ID, yang 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.integrations.bigquery import BigQueryCredentialsConfig
from google.adk.integrations.bigquery import BigQueryToolset
from google.adk.models import Gemini
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from google.genai import types
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Add it to data_science_agent/.env: 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 Agent 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 Runtime, 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(
        model="gemini-3.8-flash",
        # gemini-3.8-flash is served from the global endpoint. The agent
        # itself runs in GOOGLE_CLOUD_LOCATION (us-central1).
        client_kwargs={"location": "global"},
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    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 bahas 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 Bank Memori untuk 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 Runtime. name harus cocok dengan nama direktori (data_science_agent) — adk web menggunakannya untuk menemukan dan memuat agen.
4. instruction memberi tahu agen untuk menggunakan project penagihan untuk kueri SQL dan mengingat preferensi pengguna.
5. Gemini dengan client_kwargs={"location": "global"} mengirimkan panggilan model ke endpoint global, tempat gemini-3.8-flash tersedia. Agen itu sendiri berjalan di us-central1: adk deploy menetapkan GOOGLE_CLOUD_LOCATION pada agen yang di-deploy ke region tempat Anda melakukan deployment, sehingga lokasi model ditetapkan dalam kode.

4. Men-deploy ke Agent Runtime

Buat file requirements.txt di direktori data_science_agent:

google-adk
google-genai
google-auth
google-cloud-bigquery
python-dotenv
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk dan google-genai: ADK dan klien Gemini
• google-auth: Autentikasi Google Cloud
• google-cloud-bigquery: library klien BigQuery yang digunakan BigQueryToolset. ADK tidak menginstalnya secara default.
• python-dotenv: memuat file .env saat startup
• Tiga paket opentelemetry-instrumentation-* memungkinkan fitur pengamatan yang akan Anda pelajari nanti. Mereka menginstrumentasi panggilan model Gemini dan komunikasi gRPC/HTTP internal sehingga rekaman aktivitas muncul di tab Traces agen Anda.

Jangan tambahkan google-cloud-aiplatform ke requirements.txt Anda, meskipun Anda menginstalnya secara lokal. adk deploy akan menambahkannya untuk Anda (bersama dengan versi ADK yang Anda deploy), tetapi hanya jika requirements.txt Anda belum mencantumkannya. Mendeklarasikannya sendiri dapat menyebabkan konflik versi paket OpenTelemetry yang secara diam-diam merusak instrumentasi, sehingga menyebabkan trace tidak muncul di tab Traces.

adk deploy juga membaca file data_science_agent/.env yang Anda buat sebelumnya dan menetapkan setelannya pada agen yang di-deploy.

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

uv run adk deploy agent_engine \
  --project=$(gcloud config get project) \
  --region=us-central1 \
  --display_name="Data Science Agent" \
  --otel_to_cloud \
  data_science_agent

Di dekat awal, output menampilkan dua garis kuning, Ignoring GOOGLE_CLOUD_PROJECT in .env ... dan Ignoring GOOGLE_CLOUD_LOCATION in .env .... Nilai tersebut diharapkan: flag --project dan --region lebih diutamakan daripada nilai yang sama di .env.

Bendera	Tujuan
--project / --region	Project dan region Google Cloud target
--display_name	Nama yang mudah dibaca yang ditampilkan di Konsol Cloud
--otel_to_cloud	Mengekspor log dan trace OpenTelemetry ke Google Cloud, serta mengaktifkan telemetri (GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true) pada agen yang di-deploy

Deployment biasanya memerlukan waktu 5–10 menit. Setelah selesai, output akan menampilkan nama resource agen Anda (projects/.../reasoningEngines/) dan link untuk melihatnya di Konsol Cloud.

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

Jika link yang dicetak oleh adk deploy tidak berfungsi, buka halaman Deployments di Konsol Cloud, lalu klik agen Anda.

Saat di-deploy ke Agent Runtime, dua kemampuan akan otomatis diaktifkan:

• Memory Bank: adk deploy menghubungkan agen ke Sesi dan Memory Bank di instance Agent Runtime-nya. PreloadMemoryTool membaca dari Memory Bank 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 agen layanan Agent Runtime (Agen Layanan AI Platform Reasoning Engine). Saat di-deploy, agen berjalan sebagai akun layanan yang dikelola Google ini (bukan kredensial pribadi Anda), sehingga memerlukan izin eksplisit untuk menjalankan kueri SQL.

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get 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 $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $(gcloud config get 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 Deployments di Konsol Google Cloud. Klik agen yang di-deploy, lalu klik tab 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" (Buat daftar tabel di 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?"
   • Diharapkan: 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. "Remember that my favorite dataset is bigquery-public-data.hacker_news" (Ingat bahwa set data favorit saya adalah bigquery-public-data.hacker_news)
2. "Tabel apa saja yang ada di dalamnya?"

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

Sekarang mulai sesi baru dengan mengklik Sesi Baru di Playground, lalu ajukan pertanyaan:

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 Memory Bank melalui callback_context.add_session_to_memory()
• PreloadMemoryTool mengambil memori yang relevan sebelum setiap panggilan LLM
• Memory Bank 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 memerlukan waktu beberapa saat untuk diselesaikan.

8. Mempelajari 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 aktivitas, 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 --otel_to_cloud, adk deploy akan membuat penampung yang menjalankan server API ADK dengan OpenTelemetry diaktifkan. Di Agent Runtime, server menginisialisasi pipeline OpenTelemetry yang:

1. Membuat TracerProvider dengan pengekspor OTLP yang mengirimkan rentang ke telemetry.googleapis.com
2. Mencatat rentang ADK sendiri untuk menjalankan agen, panggilan model, dan panggilan alat, serta menggunakan tiga paket instrumentasi dari requirements.txt Anda untuk menambahkan rentang dari library utama (Gemini, httpx, gRPC)
3. Mengelompokkan dan mengekspor rentang ke Telemetry API, tempat tab Aktivitas membaca rentang tersebut

Penampung yang di-deploy mencakup ADK dan OpenTelemetry SDK serta eksportir, tetapi tidak mencakup paket instrumentasi. Itulah sebabnya requirements.txt mencantumkan ketiganya. Tanpa itu, server ADK API akan mencatat peringatan dan melewati rentang tersebut.

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=$(gcloud config get project) | grep telemetry
2. Periksa peringatan di Cloud Logging: buka Logging > Logs Explorer dan cari "proceeding without" atau "GoogleGenAiSdkInstrumentor". Peringatan yang menyebutkan instrumentasi (GenAI, HTTPX, atau gRPC) berarti paket opentelemetry-instrumentation-* yang cocok tidak ada di requirements.txt Anda.
3. Jangan tambahkan google-cloud-aiplatform ke requirements.txt Anda. adk deploy menambahkannya secara otomatis; mendeklarasikannya sendiri dapat menyebabkan konflik paket OpenTelemetry dan merusak instrumentasi secara diam-diam.

9. Pembersihan

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

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

Kueri BigQuery dalam codelab ini menggunakan set data publik, yang tidak dikenai 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 <YOUR_PROJECT_ID>

Secara opsional, bersihkan lingkungan lokal Anda:

cd ~
rm -rf ~/adk-deploy-scale

10. Selamat

Anda telah membangun agen ilmu data stateful dan men-deploy-nya ke Agent Runtime.

Yang telah Anda pelajari

• Cara membuat agen ADK dengan BigQueryToolset untuk akses data nyata
• 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 Runtime dan mengaktifkan kemampuan pengamatan dengan Cloud Trace

Langkah berikutnya

• Membuat kueri set data BigQuery pribadi Anda sendiri dengan memberikan akses agen layanan Agent Runtime 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 Runtime
• Dokumentasi Memory Bank
• Panduan Deployment Agent Runtime