Agen Data Science Stateful di Agent Engine

1. Ringkasan

Dalam codelab ini, Anda akan membuat 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 ini menggunakan tiga kemampuan inti yang diaktifkan secara progresif:

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

Yang akan Anda pelajari

• Cara membuat agen ADK dengan BigQueryToolset untuk akses data real
• Cara mengonfigurasi Memory Bank 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 observabilitas memori

Yang akan Anda butuhkan

• Project Google Cloud yang mengaktifkan penagihan
• Google Cloud SDK (gcloud CLI)
• 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 untuk developer tingkat menengah yang memiliki pemahaman tentang Python dan Google Cloud.

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

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

2. Menyiapkan lingkungan Anda

Membuat 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

Buka Editor Cloud Shell di project GCP yang Anda buat.

Kemudian, buat Terminal > Terminal Baru, dan jalankan perintah berikut.

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

Mengaktifkan API

Di terminal, jalankan perintah berikut.

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) — Trace OpenTelemetry untuk observabilitas agen

Pengaktifan API mungkin memerlukan waktu hingga satu menit untuk diterapkan. Jika Anda melihat error "API not enabled" pada langkah berikutnya, 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 adk CLI yang akan Anda gunakan untuk menguji dan men-deploy agen.

3. Membuat Agen

Buat direktori project agen baru. Semua perintah berikutnya harus dijalankan dari direktori kerja ini (induk 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 pada langkah Deployment.

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 dijalankan 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 — alat ini dapat menjelajahi skema dan mengkueri set data apa pun yang dapat diakses pemanggil.
2. PreloadMemoryTool secara otomatis mengambil memori yang relevan sebelum setiap panggilan LLM dengan menelusuri Memory Bank untuk konten yang terkait dengan pesan pengguna. Callback _save_memory mempertahankan sesi ke Memory Bank setelah setiap agen berjalan, sehingga agen dapat mengingat konteks dalam sesi mendatang.
3. App menggabungkan agen root ke dalam aplikasi yang dapat di-deploy yang dapat ditayangkan oleh Agent Engine. name harus cocok dengan nama direktori (data_science_agent) — adk web menggunakan nama ini untuk menemukan dan memuat agen.
4. instruction 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 startup
• Empat paket opentelemetry-instrumentation-* mengaktifkan fitur observabilitas yang akan Anda pelajari nanti. Paket ini menginstrumentasi permintaan HTTP FastAPI, panggilan model Gemini, dan komunikasi gRPC/HTTP internal sehingga trace 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 trace 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 lengkap dan respons agen, yang berguna untuk proses debug.

Setelan OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT mencatat konten lengkap perintah pengguna dan respons agen ke Cloud Logging. Hal ini berguna untuk proses debug, tetapi dapat menangkap data sensitif atau PII. Dalam produksi, tetapkan setelan ini ke false atau pastikan Anda memiliki 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 dan 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/

Sambil 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 dan klik agen Anda.

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

• Memory Bank: PreloadMemoryTool terhubung ke Agent Engine Memory Bank dan _save_memory mempertahankan sesi secara otomatis.
• Observability: Cloud Trace menangkap 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 di 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. "Find the number of posts per year in bigquery-public-data.hacker_news.full"
   • Diharapkan: Agen memanggil execute_sql dengan kueri SQL dan menampilkan tabel tahun dan jumlah postingan.
3. "What was the year-over-year percentage change in posts?"
   • Diharapkan: Agen memanggil execute_sql dengan kueri SQL yang menghitung perubahan persentase dan menampilkan hasilnya.

7. Menguji Persistensi Memori

Masih di Playground, ajarkan preferensi kepada agen:

1. "Remember that my favorite dataset is bigquery-public-data.hacker_news"
2. "What tables does it have?"

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

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

3. "What is my favorite dataset?"

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

• _save_memory mempertahankan 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 untuk diselesaikan.

8. Menjelajahi Observabilitas

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

Anda akan melihat tabel Sesi yang mencantumkan sesi dari kueri pengujian yang Anda jalankan pada 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 trace-nya, termasuk:

• Grafik asiklik terarah (DAG) dari rentangnya — menampilkan perincian langkah demi langkah dari penalaran agen, panggilan alat (kueri BigQuery), dan latensi
• Input dan output untuk setiap rentang (diaktifkan melalui var lingkungan OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT di .env)
• Atribut metadata seperti ID rentang, ID trace, dan waktu

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

Trace mungkin memerlukan waktu 1–2 menit untuk muncul setelah kueri selesai. Jika Anda belum melihat trace, 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 rentang ke telemetry.googleapis.com
2. Menggunakan empat paket instrumentasi dari requirements.txt Anda untuk menangkap rentang dari library utama (FastAPI, Gemini, httpx, gRPC) — google-genai diinstrumentasi secara eksplisit oleh runtime, sedangkan yang lainnya berkontribusi melalui penemuan otomatis OpenTelemetry
3. Mengelompokkan dan mengekspor rentang ke Telemetry API, tempat tab Traces membacanya

Image dasar Agent Engine menyediakan SDK dan pengekspor OpenTelemetry, tetapi tidak menyertakan paket instrumentasi. Itulah sebabnya requirements.txt Anda harus mencantumkan keempatnya — tanpa paket tersebut, tidak ada rentang yang dibuat dan tidak ada trace yang muncul.

Pemecahan masalah

Jika tidak ada trace yang muncul setelah beberapa menit:

1. Pastikan Telemetry API diaktifkan — Anda mengaktifkannya pada 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 telusuri "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 secara diam-diam merusak instrumentasi.

9. Pembersihan

Untuk menghindari biaya 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 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:

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 real
• 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 observabilitas dengan Cloud Trace

Langkah berikutnya

• Mengkueri 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
• Menyiapkan dasbor observabilitas 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