Keynote Developer Next ‘26: Meningkatkan Kualitas Agen dengan Memori

1. Pengantar

Dalam codelab ini, Anda akan meningkatkan kualitas agen ADK dengan menambahkan pengetahuan persisten dan khusus. Anda akan mempelajari cara mengelola status percakapan dengan Sesi Platform Agen, mengaktifkan pembelajaran jangka panjang dengan Memory Bank, dan mengintegrasikan data aturan kota yang kompleks menggunakan Spark dan AlloyDB untuk RAG (Retrieval-Augmented Generation).

Yang akan Anda lakukan

  • Konfigurasi Sesi Platform Agen untuk persistensi percakapan.
  • Terapkan Bank Memori agar agen dapat belajar dari interaksi sebelumnya.
  • Gunakan Spark Lightning Engine untuk menyerap dan memproses dokumentasi aturan kota.
  • Bangun sistem RAG menggunakan AlloyDB dan penelusuran vektor.
  • Men-deploy agen yang ditingkatkan ke Agent Platform.

Yang Anda butuhkan

Perkiraan durasi: 60 menit

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

2. Sebelum memulai

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.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.

  1. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
  2. Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:
    gcloud auth list
  3. Pastikan project Anda dikonfigurasi:
    gcloud config get project
  4. Jika project Anda tidak ditetapkan seperti yang diharapkan, tetapkan project:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Verifikasi autentikasi:

gcloud auth list

Konfirmasi project Anda:

gcloud config get project

Tetapkan jika perlu:

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

Mengaktifkan API

Jalankan perintah ini untuk mengaktifkan semua API yang diperlukan untuk pengelolaan sesi, pemrosesan Spark, dan AlloyDB:

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  alloydb.googleapis.com \
  dataproc.googleapis.com \
  documentai.googleapis.com \
  storage.googleapis.com \
  secretmanager.googleapis.com

3. Menyiapkan lingkungan Anda

Untuk codelab ini, Anda akan menggunakan lingkungan yang telah dikonfigurasi sebelumnya di repositori keynote.

  1. Clone repositori dan buka folder project:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/enhancing-agents-with-memory
  1. Siapkan lingkungan virtual Python dan instal paket ADK yang diperlukan:
uv venv
source .venv/bin/activate
uv sync

Mengonfigurasi Variabel Lingkungan

Agen memerlukan konfigurasi khusus untuk terhubung ke Platform Agen dan AlloyDB.

  1. Salin file lingkungan contoh:
cp .env.example .env
  1. Buka .env dan perbarui kolom berikut:
    • GOOGLE_CLOUD_PROJECT: Project ID Anda.
    • GOOGLE_CLOUD_LOCATION: us-central1.
    • ALLOYDB_CLUSTER_ID: rules-db.
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_REGION=us-central1
ALLOYDB_CLUSTER_ID=rules-db
  1. Jalankan skrip helper berikut untuk membuat instance Agent Engine yang akan digunakan untuk sesi percakapan dan memori jangka panjang. Tindakan ini akan otomatis mengisi AGENT_ENGINE_ID dalam file .env Anda:
uv run utils/setup_agent_engine.py

Setelah berhasil, Anda akan melihat:

Creating Agent Engine instance...
Successfully created Agent Engine. ID: 1234567890
Updated .env with AGENT_ENGINE_ID=1234567890

4. Membuat agen dengan Pengelolaan Sesi

Pada langkah ini, Anda akan menginisialisasi Marathon Planner Agent yang dapat mempertahankan histori percakapan di beberapa giliran. Hal ini dicapai menggunakan class App ADK dan Sesi Platform Agen.

Menginisialisasi Layanan Agen dan Sesi

Buka planner_agent/agent.py. Anda akan melihat cara menambahkan class ADK untuk mengintegrasikan Sesi Platform Agen. Hal ini memungkinkan kita membuat agen kita memiliki status dari waktu ke waktu, dan mengubah konteks sesuai kebutuhan.

from google.adk.agents import LlmAgent
from google.adk.sessions import VertexAiSessionService
from vertexai.agent_engines import AdkApp

PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT")
REGION = os.environ.get("GOOGLE_CLOUD_REGION", "us-central1")

# Initialize Vertex AI for regional services
if PROJECT_ID:
    vertexai.init(project=PROJECT_ID, location=REGION)

# Define the agent logic
root_agent = LlmAgent(
    name="planner_agent",
    model="gemini-3-flash-preview",
    instruction="You are a helpful marathon planning assistant...",
    tools=[] # We will add tools in the next steps
)

def session_service_builder():
    """Builder for Agent Platform Sessions."""
    return VertexAiSessionService(project=PROJECT_ID, location=REGION)

# Wrap the agent in an AdkApp to manage stateful context
app = AdkApp(
    agent=root_agent,
    session_service_builder=session_service_builder
)

5. Mengaktifkan Pembelajaran Jangka Panjang dengan Memory Bank

Meskipun pengelolaan sesi melacak setiap percakapan, Anda dapat melakukan hal yang sama untuk memori jangka panjang. Pada langkah ini, Anda akan melampirkan agen ke Bank Memori Platform Agen, layanan memori yang siap digunakan perusahaan dan terkelola sepenuhnya.

Melakukan inisialisasi Layanan Memory Bank

Memory Bank memungkinkan agen mengingat konteks di berbagai sesi. Perbarui planner_agent/agent.py untuk menyertakan layanan memori:

from google.adk.memory import VertexAiMemoryBankService

def memory_service_builder():
    """Builder for Agent Platform Memory Bank."""
    return VertexAiMemoryBankService(
        project=PROJECT_ID,
        location=REGION,
        agent_engine_id=AGENT_ENGINE_ID
    )

Menerapkan Penyerapan Memori Otomatis

Untuk memastikan agen belajar dari setiap giliran, kita menambahkan after_agent_callback. Fungsi ini dipicu setelah agen menyelesaikan respons, sehingga agen dapat "mencerna" sesi dan menyimpan memori yang relevan ke bank.

  1. Tentukan fungsi callback:
async def auto_save_memories(callback_context):
    """Callback to ingest the session into the memory bank after the turn."""
    # In AdkApp, the memory service is available via the invocation context
    if hasattr(callback_context._invocation_context, 'memory_service') and callback_context._invocation_context.memory_service:
        await callback_context._invocation_context.memory_service.add_session_to_memory(
            callback_context._invocation_context.session
        )
  1. Lampirkan callback ke LlmAgent:
root_agent = LlmAgent(
    # ... other params
    after_agent_callback=[auto_save_memories],
)

6. Menyiapkan AlloyDB untuk RAG

Sebelum dapat menyerap data aturan kota, kita memerlukan database berperforma tinggi untuk menyimpannya. Pada langkah ini, Anda akan membuat cluster AlloyDB dan melakukan inisialisasi skema database untuk penelusuran vektor.

1. Buat Cluster dan Instance Utama AlloyDB

Jalankan perintah ini di Cloud Shell untuk membuat cluster dan instance utamanya:

# Create the cluster
gcloud alloydb clusters create rules-db \
  --password=postgres \
  --region=us-central1

# Create the primary instance with IAM authentication enabled
gcloud alloydb instances create rules-db-primary \
  --instance-type=PRIMARY \
  --cpu-count=2 \
  --region=us-central1 \
  --cluster=rules-db \
  --database-flags=alloydb.iam_authentication=on

2. Memberikan Peran IAM yang Diperlukan

Untuk menggunakan server MCP AlloyDB terkelola, identitas Anda memerlukan izin tertentu. Jalankan perintah berikut untuk memberikan peran yang diperlukan:

export USER_EMAIL=$(gcloud config get-value account)

# Role to use MCP tools
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$USER_EMAIL" \
  --role="roles/mcp.toolUser"

# Role to execute SQL in AlloyDB
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$USER_EMAIL" \
  --role="roles/alloydb.admin"

# Role for IAM database authentication
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="user:$USER_EMAIL" \
  --role="roles/alloydb.databaseUser"

# Create the IAM-based database user
gcloud alloydb users create "$USER_EMAIL" \
  --cluster=rules-db \
  --region=us-central1 \
  --type=IAM_BASED

3. Membuat Database dan Tabel melalui AlloyDB Studio

Karena database dan tabel AlloyDB dikelola melalui SQL, kita akan menggunakan AlloyDB Studio di Konsol Google Cloud untuk menyelesaikan skema.

  1. Buka AlloyDB > Clusters, lalu klik rules-db.
  2. Di menu navigasi sebelah kiri, klik AlloyDB Studio.
  3. Login menggunakan pengguna postgres dan sandi yang Anda tetapkan (postgres).
  4. Jalankan SQL berikut untuk membuat database: 
    CREATE DATABASE city_rules;
  5. Alihkan koneksi database Anda ke city_rules di AlloyDB Studio, lalu jalankan SQL berikut untuk menginstal ekstensi dan membuat tabel rules: 
    -- Install extensions for vector search and ML
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;

-- Create the rules table
CREATE TABLE IF NOT EXISTS rules (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    text TEXT NOT NULL,
    city TEXT NOT NULL,
    embedding vector(3072) DEFAULT NULL
);

-- Grant your IAM user access to the table (replace with your email)
GRANT ALL PRIVILEGES ON TABLE rules TO "YOUR_EMAIL_ADDRESS";

7. Menyerap Data Aturan Kota dengan Spark Lightning Engine

Untuk memberikan perencanaan yang benar-benar akurat, agen memerlukan lebih dari sekadar perintah yang dibuat dengan baik; agen memerlukan perujukan dalam data dan konteks organisasi. Pada langkah ini, Anda akan menggunakan Spark Lightning Engine di Dataproc Serverless untuk memproses PDF aturan kota yang besar dan menyerapnya ke AlloyDB.

Mengapa Spark Lightning Engine?

Mendasarkan agen dalam skala besar memerlukan pemrosesan data tidak terstruktur dalam jumlah besar. Spark Lightning Engine adalah mesin eksekusi berperforma tinggi untuk Spark yang secara signifikan mempercepat workload ini. Kita menggunakannya di sini untuk melakukan pengelompokan semantik pada dokumen menggunakan Document AI Google.

Mempelajari Pipeline Spark

Logika penyerapan ditentukan dalam spark-setup/spark_alloydb_processor.py. Pipeline mengikuti langkah-langkah berikut:

  1. Mencantumkan PDF: Mengambil URI dokumen dari bucket Google Cloud Storage.
  2. Ekstraksi Semantik: Menggunakan UDF (User Defined Function) untuk memanggil Document AI API.
  3. Menulis ke AlloyDB: Menyimpan potongan teks yang diekstrak ke dalam tabel AlloyDB bernama rules.
# Extract from spark_alloydb_processor.py
def process_document(gcs_uri: str):
    # ... calls Document AI to parse PDF ...
    return chunks

# Parallel processing with Spark Lightning Engine
process_udf = udf(process_document, chunk_schema)
chunked_df = uri_df.withColumn("chunks", process_udf(col("gcs_uri"))) \
                   .select(explode(col("chunks")).alias("chunk")) \
                   .select("chunk.*")

# Save to AlloyDB for Vector Search
chunked_df.write.format("jdbc") \
    .option("url", jdbc_url) \
    .option("dbtable", "rules") \
    .mode("append") \
    .save()

Menjalankan Tugas Penyerapan

Picu proses penyerapan menggunakan skrip yang disediakan:

./spark-setup/run_dataproc.sh

8. RAG dengan AlloyDB

Setelah data aturan kota berada di AlloyDB, agen dapat menggunakannya untuk melakukan Retrieval-Augmented Generation (RAG). Hal ini memastikan rencana maraton mematuhi kode kota tertentu.

Kemampuan AlloyDB untuk RAG

AlloyDB unggul dalam penelusuran vektor, sehingga memungkinkan kita menyimpan data terstruktur dan embedding vektor di tempat yang sama. Agen dapat menggunakan fungsi embedding bawaan di AlloyDB untuk menemukan informasi aturan yang paling relevan.

Untuk memberi agen akses ke data ini, kami menyediakan alat yang membuat kueri AlloyDB menggunakan kemiripan vektor. Anda dapat melihat logika ini di hybrid_recall.sql, yang menunjukkan cara menghitung jarak antara kueri dan aturan tersimpan kami:

SELECT
    text,
    (embedding <=> 
     embedding('gemini-embedding-001', 
               'Restrictions for running a race on the Las Vegas strip')::vector) 
    as distance
FROM
    rules
WHERE city = 'Las Vegas'
ORDER BY
    distance ASC
LIMIT 5;

Menyematkan Agen dalam Aturan Lokal dengan Alat RAG

Agar alat tersedia untuk agen, Anda harus menentukannya di planner_agent/tools.py, lalu mendaftarkannya di planner_agent/agent.py. Kita akan menggunakan server MCP AlloyDB jarak jauh terkelola dari Google Cloud untuk terhubung ke database kita.

  1. Tentukan alat di planner_agent/tools.py menggunakan pola "Hybrid Recall". Kita akan menggunakan protokol streamable_http untuk terhubung ke server MCP AlloyDB terkelola:
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def get_local_and_traffic_rules(query: str) -> str:
    """Uses vector search in AlloyDB via managed MCP server."""
    # Vector search query using built-in AlloyDB embedding functions
    sql = f"SELECT text FROM rules WHERE city = 'Las Vegas' ORDER BY embedding <=> google_ml.embedding('gemini-embedding-001', '{query}')::vector ASC LIMIT 5;"
    
    # Establish a streamable HTTP connection to the MCP server
    async with streamablehttp_client(url, headers=get_auth_headers()) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            result = await session.call_tool(
                "execute_sql",
                arguments={
                    "instance": full_instance_name,
                    "database": "city_rules",
                    "sqlStatement": sql
                }
            )
            return "\n".join([c.text for c in result.content if hasattr(c, 'text')])
  1. Daftarkan alat dan selesaikan planner_agent/agent.py:
# ... imports ...

# Assemble the Agent
root_agent = LlmAgent(
    name="planner_agent",
    model="gemini-3-flash-preview",
    instruction="You are a helpful marathon planning assistant...",
    tools=[
        get_local_and_traffic_rules,
    ],
    after_agent_callback=[auto_save_memories],
)

# 2. Wrap the agent in an AdkApp to manage the stateful lifecycle
app = AdkApp(
    agent=root_agent,
    session_service_builder=session_service_builder,
    memory_service_builder=memory_service_builder
)

9. Panduan Pakar dengan Keterampilan Agen

Keterampilan Agen adalah modul mandiri yang memberikan petunjuk, panduan, dan sumber daya khusus untuk membantu agen melakukan tugas secara lebih efektif. Daripada membuat perintah sistem Anda berantakan dengan petunjuk yang rumit untuk setiap alat, Anda dapat merangkum keahlian tersebut ke dalam Keterampilan yang dimuat hanya saat diperlukan.

Google menyediakan keterampilan bawaan untuk produk Google (seperti AlloyDB dan BigQuery) guna memastikan agen Anda mengikuti praktik terbaik industri untuk membuat kueri data dan mengelola resource. Anda dapat menjelajahi pola khusus ini dan pola lainnya di Google Skills Depot. Anda akan menemukan keterampilan dasar AlloyDB di sini.

1. Mempelajari File Keterampilan

Buka file skill yang telah dikonfigurasi sebelumnya di planner_agent/skills/get-local-and-traffic-rules/SKILL.md. Berikut tampilannya:

---
name: get-local-and-traffic-rules
description: Retrieve local rules and traffic information for a specific jurisdiction.
---
# get_local_and_traffic_rules Skill

This skill provides guidelines on how to effectively use the `get_local_and_traffic_rules` tool.

## Overview
The `get_local_and_traffic_rules` tool interfaces with an AlloyDB database to perform vector similarity searches on a corpus of rules and traffic information using a provided natural language query.

## Usage Guidelines
1. **Query Specificity**: When calling the tool, provide specific details in the `query` argument. For example, instead of querying "food rules", use "rules regarding food vendors during public events".
2. **Contextual Use**: Use the tool when planning events or activities that require adherence to local municipal or state rules (e.g., street closures, noise ordinances, environmental rules).
3. **Handling Results**: The tool returns a string containing the text of the top 5 most relevant rules. If no error occurs, parse the returned string to inform your planning tasks.
4. **Error Handling**: If an error string is returned (e.g., "Error querying rules: ..."), you must report this failure or attempt an alternative approach if applicable.

## Underlying Mechanism
- The tool uses `google_ml.embedding` to convert the query into a vector representation.
- It calculates distance (`<=>`) against the `embedding` column in the `rules` table on an AlloyDB instance.
- Results are fetched in descending order of similarity, limited to 5 results.

2. Cara Mendaftarkan Keterampilan

Di planner_agent/agent.py, keahlian dimuat dari direktori dan ditambahkan ke alat agen. Berikut tampilan kodenya:

import pathlib
from google.adk.skills import load_skill_from_dir
from google.adk.tools import skill_toolset

# Load the AlloyDB skill from its directory
alloydb_skill = load_skill_from_dir(pathlib.Path(__file__).parent / "skills" / "get-local-and-traffic-rules")

# Assemble the Agent with the Skill Toolset
root_agent = LlmAgent(
    name="planner_agent",
    model="gemini-3-flash-preview",
    instruction="You are a helpful marathon planning assistant...",
    tools=[
        get_local_and_traffic_rules,
        skill_toolset.SkillToolset(skills=[alloydb_skill])
    ],
    after_agent_callback=[auto_save_memories],
)

10. Menguji Agen

  1. Mulai agen secara lokal:
uv run adk run planner_agent
  1. Ajukan pertanyaan tentang peraturan kota: [user]: What are the rules for running a race on the Las Vegas strip?

Agen akan memanggil alat get_local_and_traffic_rules, melakukan penelusuran vektor di AlloyDB, dan menampilkan jawaban berdasarkan potongan aturan resmi yang diproses oleh Spark.

11. Men-deploy Agen

Men-deploy ke Platform Agen

uv run adk deploy agent_engine \
  --env_file .env \
  planner_agent

12. Pembersihan

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

Menghapus Cluster AlloyDB

# Delete the AlloyDB Cluster
gcloud alloydb clusters delete rules-db --region=us-central1 --force

Menghapus Aplikasi Runtime Agen

Anda dapat menghapus instance Reasoning Engine melalui konsol atau menggunakan perintah gcloud (jika Anda memiliki nama resource). Untuk mempermudah, gunakan konsol:

  1. Buka halaman Agent Runtime.
  2. Pilih planner_agent –> klik tombol tiga titik di sisi kanan.
  3. Klik Hapus.

13. Selamat

Selamat! Anda telah berhasil meningkatkan kualitas agen ADK dengan kemampuan perujukan data dan memori tingkat lanjut.

Yang telah Anda pelajari

  • Agen Stateful: Mengintegrasikan Sesi Platform Agen untuk mempertahankan konteks percakapan.
  • Pembelajaran Jangka Panjang: Melampirkan Bank Memori Platform Agen agar agen dapat belajar dari interaksi pengguna.
  • Penyerapan Data: Menggunakan Spark Lightning Engine dan Document AI untuk memproses dokumen tidak terstruktur.
  • RAG: Membangun sistem penelusuran vektor di AlloyDB untuk mendasarkan agen pada aturan dunia nyata.

Langkah Berikutnya