Next '26 Developer Keynote: Enhancing Agents with Memory

1. Giriş

Bu codelab'de, kalıcı ve özel bilgiler ekleyerek ADK aracılarınızı bir sonraki seviyeye taşıyacaksınız. Agent Platform Sessions ile görüşme durumunu yönetmeyi, Memory Bank ile uzun vadeli öğrenmeyi etkinleştirmeyi ve RAG (Retrieval-Augmented Generation) için Spark ve AlloyDB kullanarak karmaşık şehir kuralları verilerini entegre etmeyi öğreneceksiniz.

Yapacaklarınız

  • Sohbetin devamlılığı için Agent Platform Sessions'ı (Aracı Platformu Oturumları) yapılandırın.
  • Temsilcilerin önceki etkileşimlerden bilgi edinmesini sağlamak için Hafıza Bankası'nı uygulayın.
  • Şehir kuralları dokümanlarını almak ve işlemek için Spark Lightning Engine'i kullanın.
  • AlloyDB ve vektör aramayı kullanarak RAG sistemi oluşturun.
  • Geliştirilmiş ajanı Agent Platform'a dağıtın.

İhtiyacınız olanlar

Tahmini süre: 60 dakika

Bu kod laboratuvarında oluşturulan kaynakların maliyeti 5 ABD dolarından az olmalıdır.

2. Başlamadan önce

Google Cloud projesi oluşturma

  1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i Başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

  1. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
  2. Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:
    gcloud auth list
  3. Projenizin yapılandırıldığını onaylayın:
    gcloud config get project
  4. Projeniz beklendiği gibi ayarlanmamışsa şu şekilde ayarlayın:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Kimlik doğrulamayı doğrulayın:

gcloud auth list

Projenizi onaylayın:

gcloud config get project

Gerekirse ayarlayın:

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

API'leri etkinleştir

Oturum yönetimi, Spark işleme ve AlloyDB için gerekli tüm API'leri etkinleştirmek üzere şu komutu çalıştırın:

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. Ortamınızı ayarlama

Bu codelab'de, keynote deposundaki önceden yapılandırılmış ortamı kullanacaksınız.

  1. Depoyu klonlayın ve proje klasörüne gidin:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/enhancing-agents-with-memory
  1. Python sanal ortamı oluşturun ve gerekli ADK paketlerini yükleyin:
uv venv
source .venv/bin/activate
uv sync

Ortam değişkenlerini yapılandırma

Aracının, Agent Platform ve AlloyDB'ye bağlanmak için belirli bir yapılandırmaya ihtiyacı vardır.

  1. Örnek ortam dosyasını kopyalayın:
cp .env.example .env
  1. .env açın ve aşağıdaki alanları güncelleyin:
    • GOOGLE_CLOUD_PROJECT: Proje kimliğiniz.
    • 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. Sohbet oturumlarında ve uzun süreli hafızada kullanılacak bir Agent Engine örneği oluşturmak için aşağıdaki yardımcı komut dosyasını çalıştırın. Bu işlemle .env dosyanızdaki AGENT_ENGINE_ID otomatik olarak doldurulur:
uv run utils/setup_agent_engine.py

İşlem başarılı olduğunda şunları görürsünüz:

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

4. Oturum Yönetimi ile temsilci oluşturma

Bu adımda, birden fazla adımda sohbet geçmişini koruyabilen bir Maraton Planlayıcı Aracısı başlatacaksınız. Bu, ADK App sınıfı ve Agent Platform Sessions kullanılarak gerçekleştirilir.

Aracı ve Oturum Hizmeti'ni başlatma

planner_agent/agent.py adlı kişiyi aç. Agent Platform Sessions'ı entegre etmek için nasıl ADK sınıfı eklediğimizi göreceksiniz. Bu sayede, zaman içinde aracılarımızı durum bilgili hale getirebilir ve bağlamı gerektiği gibi değiştirebiliriz.

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. Hafıza Bankası ile uzun süreli öğrenmeyi etkinleştirme

Oturum yönetimi, tek tek görüşmeleri izlerken uzun süreli hafıza için de aynı şeyi yapabilirsiniz. Bu adımda, temsilciyi kurumsal kullanıma hazır ve tümüyle yönetilen bir bellek hizmeti olan Agent Platform'un Bellek Bankası'na bağlayacaksınız.

Bellek Bankası Hizmeti'ni başlatma

Memory Bank, temsilcinin farklı oturumlardaki bağlamı hatırlamasını sağlar. Bellek hizmetini eklemek için planner_agent/agent.py uygulamasını güncelleyin:

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
    )

Otomatik bellek alımını uygulama

Temsilcinin her dönüşten ders çıkarmasını sağlamak için after_agent_callback ekliyoruz. Bu işlev, temsilci bir yanıtı tamamladıktan sonra tetiklenir. Böylece oturumun "özetini" çıkarabilir ve ilgili anıları bankaya kaydedebilir.

  1. Geri çağırma işlevini tanımlayın:
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. Geri çağırma işlevini LlmAgent öğesine ekleyin:
root_agent = LlmAgent(
    # ... other params
    after_agent_callback=[auto_save_memories],
)

6. RAG için AlloyDB'yi ayarlama

Şehir kuralları verilerini alabilmemiz için bu verileri depolayacak yüksek performanslı bir veritabanına ihtiyacımız var. Bu adımda bir AlloyDB kümesi oluşturacak ve vektör araması için veritabanı şemasını başlatacaksınız.

1. AlloyDB kümesini ve birincil örneğini oluşturma

Kümenizi ve birincil örneğini oluşturmak için Cloud Shell'de aşağıdaki komutları çalıştırın:

# 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. Gerekli IAM rollerini verme

Yönetilen AlloyDB MCP sunucusunu kullanmak için kimliğinizin belirli izinlere sahip olması gerekir. Gerekli rolleri vermek için aşağıdaki komutları çalıştırın:

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. AlloyDB Studio ile veritabanı ve tablo oluşturma

AlloyDB veritabanları ve tabloları SQL üzerinden yönetildiğinden şemayı tamamlamak için Google Cloud Console'da AlloyDB Studio'yu kullanacağız.

  1. AlloyDB > Clusters'a (AlloyDB > Küme) gidin ve rules-db simgesini tıklayın.
  2. Sol gezinme menüsünde AlloyDB Studio'yu tıklayın.
  3. postgres kullanıcısını ve belirlediğiniz şifreyi (postgres) kullanarak giriş yapın.
  4. Veritabanını oluşturmak için aşağıdaki SQL'i çalıştırın: 
    CREATE DATABASE city_rules;
  5. AlloyDB Studio'da veritabanı bağlantınızı city_rules olarak değiştirin ve uzantıları yüklemek ve rules tablosunu oluşturmak için aşağıdaki SQL'i çalıştırın: 
    -- 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. Spark Lightning Engine ile Şehir Kuralları Verilerini Alma

Gerçekten doğru bir planlama sağlamak için bir aracının iyi hazırlanmış bir istemden daha fazlasına ihtiyacı vardır. Verilere ve organizasyonel bağlama temellendirme gerekir. Bu adımda, büyük şehir kuralları PDF'lerini işlemek ve AlloyDB'ye aktarmak için Dataproc Sunucusuz'da Spark Lightning Engine'i kullanacaksınız.

Neden Spark Lightning Engine?

Büyük ölçekte temellendirme aracı, büyük miktarda yapılandırılmamış verinin işlenmesini gerektirir. Spark Lightning Engine, Spark için yüksek performanslı bir yürütme motorudur ve bu iş yüklerini önemli ölçüde hızlandırır. Bu hizmeti, Google'ın Document AI'ını kullanarak dokümanlarda anlamsal parçalama işlemi yapmak için kullanırız.

Spark ardışık düzenini keşfetme

Alım mantığı spark-setup/spark_alloydb_processor.py içinde tanımlanır. İşlem hattı şu adımları izler:

  1. PDF'leri listeleme: Google Cloud Storage paketinden doküman URI'lerini alır.
  2. Anlamsal Çıkarma: Document AI API'yi çağırmak için bir UDF (Kullanıcı Tarafından Tanımlanan İşlev) kullanır.
  3. AlloyDB'ye yaz: Çıkarılan metin parçalarını rules adlı AlloyDB tablosuna kaydeder.
# 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()

Besleme işini çalıştırma

Sağlanan komut dosyasını kullanarak alım sürecini tetikleyin:

./spark-setup/run_dataproc.sh

8. AlloyDB ile RAG

Şehir kuralları verileri AlloyDB'ye yüklendiğinden artık aracı, Retrieval-Augmented Generation (RAG) gerçekleştirmek için bu verileri kullanabilir. Bu sayede maraton planının belirli şehir kodlarına uygun olması sağlanır.

AlloyDB'nin RAG için Gücü

AlloyDB, vektör arama konusunda mükemmeldir ve hem yapılandırılmış verileri hem de vektör yerleştirmelerini aynı yerde depolamamıza olanak tanır. Temsilci, en alakalı kurallar bilgisini bulmak için AlloyDB'deki yerleşik embedding işlevini kullanabilir.

Ajanın bu verilere erişebilmesi için vektör benzerliğini kullanarak AlloyDB'ye sorgu gönderen bir araç sunuyoruz. Bir sorgu ile depolanan kurallarımız arasındaki mesafenin nasıl hesaplandığını gösteren hybrid_recall.sql bölümünde bu mantığı görebilirsiniz:

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;

RAG aracıyla yerel kurallara göre Agent'ı temellendirme

Aracı ajanın kullanımına sunmak için planner_agent/tools.py bölümünde tanımlamanız ve ardından planner_agent/agent.py bölümünde kaydetmeniz gerekir. Veritabanımıza bağlanmak için Google Cloud'un yönetilen uzak AlloyDB MCP sunucusunu kullanacağız.

  1. "Karma Geri Çağırma" düzenini kullanarak aracı planner_agent/tools.py içinde tanımlayın. Yönetilen AlloyDB MCP sunucusuna bağlanmak için streamable_http protokolünü kullanacağız:
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. Aracı kaydedin ve planner_agent/agent.py işlemini tamamlayın:
# ... 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. Aracı becerileriyle uzman rehberliği

Aracı becerileri, temsilcilerin görevleri daha etkili bir şekilde yerine getirmesine yardımcı olmak için belirli talimatlar, rehberlik ve kaynaklar sağlayan bağımsız modüllerdir. Sistem isteminizi her araç için karmaşık talimatlarla doldurmak yerine, bu uzmanlığı yalnızca gerektiğinde yüklenen bir Beceri'de kapsayabilirsiniz.

Google, temsilcilerinizin verilere sorgu gönderme ve kaynakları yönetme konusunda sektördeki en iyi uygulamaları takip etmesini sağlamak için Google ürünlerine yönelik önceden oluşturulmuş beceriler (ör. AlloyDB ve BigQuery) sunar. Bu ve diğer uzmanlık alanlarına yönelik kalıpları Google Skills Depot'ta inceleyebilirsiniz. AlloyDB'nin temel becerilerini burada bulabilirsiniz.

1. Beceri Dosyasını Keşfetme

Önceden yapılandırılmış beceri dosyasını planner_agent/skills/get-local-and-traffic-rules/SKILL.md konumunda açın. Bu uzantı aşağıdaki gibi görünür:

---
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. Becerinin Kaydedilme Şekli

planner_agent/agent.py bölümünde beceri, dizinden yüklenir ve ajanın araçlarına eklenir. Kodun görünümü aşağıdaki gibidir:

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. Aracıyı test etme

  1. Aracıyı yerel olarak başlatın:
uv run adk run planner_agent
  1. Şehir kuralları hakkında soru sorun: [user]: What are the rules for running a race on the Las Vegas strip?

Aracı, get_local_and_traffic_rules aracını çağırır, AlloyDB'de vektör araması yapar ve Spark tarafından işlenen resmi kurallar parçalarına dayalı bir yanıt döndürür.

11. Aracıyı dağıtma

Agent Platform'a dağıtma

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

12. Temizleme

Devam eden ücretleri önlemek için bu codelab sırasında oluşturulan kaynakları silin.

AlloyDB kümesini silme

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

Aracı Çalışma Zamanı Uygulamasını Silme

Reasoning Engine örneğini konsol üzerinden veya gcloud komutunu kullanarak (kaynak adınız varsa) silebilirsiniz. Basitlik için konsolu kullanın:

  1. Agent Runtime sayfasına gidin.
  2. planner_agent simgesini seçin ve sağ taraftaki üç nokta düğmesini tıklayın.
  3. Sil'i tıklayın.

13. Tebrikler

Tebrikler! Bir ADK aracısını gelişmiş bellek ve veri temellendirme özellikleriyle başarıyla geliştirdiniz.

Öğrendikleriniz

  • Durum Bilgili Ajanlar: Sohbet bağlamını korumak için Ajan Platformu Oturumları'nı entegre edin.
  • Uzun Süreli Öğrenme: Temsilcinin kullanıcı etkileşimlerinden öğrenmesini sağlamak için Temsilci Platformu Bellek Bankası ekleme.
  • Veri Alımı: Yapılandırılmamış dokümanları işlemek için Spark Lightning Engine ve Document AI'ı kullanma.
  • RAG: Aracıyı gerçek dünya kurallarına dayandırmak için AlloyDB'de vektör arama sistemi oluşturma.

Sonraki Adımlar