Next '26 Developer Keynote: Enhancing Agents with Memory

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ nâng cấp tác nhân ADK bằng cách thêm kiến thức chuyên biệt và lâu dài. Bạn sẽ tìm hiểu cách quản lý trạng thái cuộc trò chuyện bằng Phiên trên Nền tảng tác nhân, cho phép học tập dài hạn bằng Ngân hàng bộ nhớ và tích hợp dữ liệu quy tắc phức tạp của thành phố bằng Spark và AlloyDB cho RAG (Tạo sinh tăng cường truy xuất).

Bạn sẽ thực hiện

Định cấu hình Phiên trên Nền tảng tác nhân để duy trì cuộc trò chuyện.
Triển khai Ngân hàng bộ nhớ để cho phép tác nhân học hỏi từ các lượt tương tác trước đó.
Sử dụng Công cụ Spark Lightning để nhập và xử lý tài liệu về quy tắc của thành phố.
Xây dựng hệ thống RAG bằng AlloyDB và tính năng tìm kiếm vectơ.
Triển khai tác nhân nâng cao lên Nền tảng tác nhân.

Bạn cần có

Một trình duyệt web như Chrome
Một dự án trên Google Cloud đã bật tính năng thanh toán
Có kiến thức cơ bản về Python và SQL

Thời lượng ước tính: 60 phút

Các tài nguyên được tạo trong lớp học lập trình này sẽ có chi phí dưới 5 USD.

2. Trước khi bắt đầu

Tạo một dự án trên Google Cloud

Trong Google Cloud Console, trên trang bộ chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán đã được bật cho một dự án hay chưa.

Bắt đầu Cloud Shell

Cloud Shell là một môi trường dòng lệnh chạy trong Google Cloud, được tải sẵn các công cụ cần thiết.

Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Cloud.
Sau khi kết nối với Cloud Shell, hãy xác minh quy trình xác thực:
```
gcloud auth list
```
Xác nhận rằng dự án của bạn đã được định cấu hình:
```
gcloud config get project
```
Nếu dự án của bạn chưa được thiết lập như mong đợi, hãy thiết lập dự án:
```
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
```

Xác minh quy trình xác thực:

gcloud auth list

Xác nhận dự án của bạn:

gcloud config get project

Thiết lập dự án nếu cần:

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

Bật API

Chạy lệnh này để bật tất cả các API cần thiết cho việc quản lý phiên, xử lý Spark và 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. Thiết lập môi trường

Trong lớp học lập trình này, bạn sẽ sử dụng môi trường được định cấu hình sẵn trong kho lưu trữ bài thuyết trình.

Nhân bản kho lưu trữ và chuyển đến thư mục dự án:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/enhancing-agents-with-memory

Thiết lập môi trường ảo Python và cài đặt các gói ADK cần thiết:

uv venv
source .venv/bin/activate
uv sync

Định cấu hình các biến môi trường

Tác nhân yêu cầu cấu hình cụ thể để kết nối với Nền tảng tác nhân và AlloyDB.

Sao chép tệp môi trường mẫu:

cp .env.example .env

Mở .env và cập nhật các trường sau:
- GOOGLE_CLOUD_PROJECT: Mã dự án của bạn.
- 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

Chạy tập lệnh trợ giúp sau để tạo một thực thể Công cụ tác nhân dùng cho các phiên trò chuyện và bộ nhớ dài hạn. Thao tác này sẽ tự động điền AGENT_ENGINE_ID vào tệp .env:

uv run utils/setup_agent_engine.py

Sau khi thành công, bạn sẽ thấy:

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

4. Tạo một tác nhân bằng tính năng Quản lý phiên

Ở bước này, bạn sẽ khởi động một Tác nhân lập kế hoạch chạy marathon có thể duy trì nhật ký trò chuyện qua nhiều lượt. Bạn có thể thực hiện việc này bằng lớp App ADK và Phiên trên Nền tảng tác nhân.

Khởi chạy Dịch vụ tác nhân và phiên

Mở planner_agent/agent.py. Bạn sẽ thấy cách chúng tôi thêm một lớp ADK để tích hợp Phiên trên Nền tảng tác nhân. Điều này giúp chúng tôi có thể duy trì trạng thái của tác nhân theo thời gian và sửa đổi ngữ cảnh khi cần.

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. Bật tính năng học tập dài hạn bằng Ngân hàng bộ nhớ

Trong khi tính năng quản lý phiên theo dõi các cuộc trò chuyện riêng lẻ, bạn có thể thực hiện tương tự cho bộ nhớ dài hạn. Ở bước này, bạn sẽ đính kèm tác nhân vào Ngân hàng bộ nhớ của Nền tảng tác nhân, một dịch vụ bộ nhớ được quản lý đầy đủ và sẵn sàng cho doanh nghiệp.

Khởi chạy Dịch vụ ngân hàng bộ nhớ

Ngân hàng bộ nhớ cho phép tác nhân nhớ lại ngữ cảnh trong các phiên khác nhau. Cập nhật planner_agent/agent.py để thêm dịch vụ bộ nhớ:

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
    )

Triển khai tính năng tự động nhập bộ nhớ

Để đảm bảo tác nhân học hỏi từ mọi lượt, chúng ta sẽ thêm after_agent_callback. Hàm này được kích hoạt sau khi tác nhân hoàn tất một câu trả lời, cho phép tác nhân "tiêu hoá" phiên và lưu các bộ nhớ có liên quan vào ngân hàng.

Xác định hàm 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
        )

Đính kèm lệnh gọi lại vào LlmAgent:

root_agent = LlmAgent(
    # ... other params
    after_agent_callback=[auto_save_memories],
)

6. Thiết lập AlloyDB cho RAG

Trước khi có thể nhập dữ liệu quy tắc của thành phố, chúng ta cần một cơ sở dữ liệu hiệu suất cao để lưu trữ dữ liệu đó. Ở bước này, bạn sẽ tạo một cụm AlloyDB và khởi chạy lược đồ cơ sở dữ liệu cho tính năng tìm kiếm vectơ.

1. Tạo cụm AlloyDB và thực thể chính

Chạy các lệnh này trong Cloud Shell để tạo cụm và thực thể chính của cụm:

# 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. Cấp các vai trò IAM bắt buộc

Để sử dụng máy chủ AlloyDB MCP được quản lý, danh tính của bạn cần có các quyền cụ thể. Chạy các lệnh này để cấp các vai trò bắt buộc:

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. Tạo cơ sở dữ liệu và bảng thông qua AlloyDB Studio

Vì cơ sở dữ liệu và bảng AlloyDB được quản lý thông qua SQL, nên chúng ta sẽ sử dụng AlloyDB Studio trong Google Cloud Console để hoàn tất lược đồ.

Chuyển đến AlloyDB > Clusters (AlloyDB > Cụm) rồi nhấp vào rules-db.
Trong trình đơn thao tác ở bên trái, hãy nhấp vào AlloyDB Studio.
Đăng nhập bằng người dùng postgres và mật khẩu bạn đã đặt (postgres).
Chạy SQL sau để tạo cơ sở dữ liệu:
```
CREATE DATABASE city_rules;
```

Chuyển kết nối cơ sở dữ liệu sang city_rules trong AlloyDB Studio và chạy SQL sau để cài đặt tiện ích cũng như tạo bảng 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. Nhập dữ liệu quy tắc của thành phố bằng Công cụ Spark Lightning

Để lập kế hoạch thực sự chính xác, một tác nhân cần nhiều hơn một câu lệnh được soạn thảo kỹ lưỡng; tác nhân cần liên kết thực tế vào dữ liệu và ngữ cảnh của tổ chức. Ở bước này, bạn sẽ sử dụng Công cụ Spark Lightning trên Dataproc Serverless để xử lý các tệp PDF lớn về quy tắc của thành phố và nhập các tệp này vào AlloyDB.

Tại sao nên sử dụng Công cụ Spark Lightning?

Việc liên kết thực tế các tác nhân ở quy mô lớn đòi hỏi phải xử lý lượng lớn dữ liệu phi cấu trúc. Công cụ Spark Lightning là một công cụ thực thi hiệu suất cao cho Spark, giúp tăng tốc đáng kể các khối lượng công việc này. Chúng ta sử dụng công cụ này ở đây để thực hiện phân đoạn ngữ nghĩa trên các tài liệu bằng Document AI của Google.

Khám phá quy trình Spark

Logic nhập được xác định trong spark-setup/spark_alloydb_processor.py. Quy trình này tuân theo các bước sau:

List PDFs (Liệt kê tệp PDF): Truy xuất URI tài liệu từ một nhóm Google Cloud Storage.
Semantic Extraction (Trích xuất ngữ nghĩa): Sử dụng UDF (Hàm do người dùng xác định) để gọi Document AI API.
Write to AlloyDB (Ghi vào AlloyDB): Lưu các đoạn văn bản đã trích xuất vào bảng AlloyDB có tên là 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()

Chạy công việc nhập

Kích hoạt quy trình nhập bằng tập lệnh được cung cấp:

./spark-setup/run_dataproc.sh

8. RAG với AlloyDB

Giờ đây, khi dữ liệu quy tắc của thành phố nằm trong AlloyDB, tác nhân có thể sử dụng dữ liệu đó để thực hiện Tạo sinh tăng cường truy xuất (RAG). Điều này đảm bảo kế hoạch chạy marathon tuân thủ các mã thành phố cụ thể.

Sức mạnh của AlloyDB cho RAG

AlloyDB vượt trội trong tính năng tìm kiếm vectơ, cho phép chúng ta lưu trữ cả dữ liệu có cấu trúc và giá trị nhúng vectơ ở cùng một nơi. Tác nhân có thể sử dụng hàm embedding tích hợp trong AlloyDB để tìm thông tin quy tắc phù hợp nhất.

Thu hồi kết hợp bằng tính năng tìm kiếm vectơ

Để cấp cho tác nhân quyền truy cập vào dữ liệu này, chúng tôi cung cấp một công cụ truy vấn AlloyDB bằng tính năng tương đồng vectơ. Bạn có thể thấy logic này trong hybrid_recall.sql, cho thấy cách tính khoảng cách giữa một truy vấn và các quy tắc được lưu trữ của chúng tôi:

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;

Căn cứ vào tác nhân trong các quy tắc địa phương bằng công cụ RAG

Để cung cấp công cụ cho tác nhân, bạn phải xác định công cụ đó trong planner_agent/tools.py, sau đó đăng ký công cụ đó trong planner_agent/agent.py. Chúng ta sẽ sử dụng máy chủ AlloyDB MCP từ xa được quản lý từ Google Cloud để kết nối với cơ sở dữ liệu.

Xác định công cụ trong planner_agent/tools.py bằng mẫu "Thu hồi kết hợp". Chúng ta sẽ sử dụng giao thức streamable_http để kết nối với máy chủ AlloyDB MCP được quản lý:

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')])

Đăng ký công cụ và hoàn tất 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. Hướng dẫn của chuyên gia bằng Kỹ năng của tác nhân

Kỹ năng của tác nhân là các mô-đun độc lập cung cấp hướng dẫn, chỉ dẫn và tài nguyên cụ thể để giúp tác nhân thực hiện các tác vụ hiệu quả hơn. Thay vì làm rối câu lệnh hệ thống bằng các hướng dẫn phức tạp cho mọi công cụ, bạn có thể đóng gói kiến thức chuyên môn đó thành một Kỹ năng chỉ được tải khi cần.

Google cung cấp các kỹ năng được tạo sẵn cho các sản phẩm của Google (như AlloyDB và BigQuery) để đảm bảo tác nhân của bạn tuân theo các phương pháp hay nhất trong ngành để truy vấn dữ liệu và quản lý tài nguyên. Bạn có thể khám phá các mẫu này và các mẫu chuyên biệt khác tại Kho kỹ năng của Google. Bạn sẽ tìm thấy các kỹ năng cơ bản của AlloyDB tại đây.

1. Khám phá tệp kỹ năng

Mở tệp kỹ năng được định cấu hình sẵn tại planner_agent/skills/get-local-and-traffic-rules/SKILL.md. Đây là giao diện của tệp này:

---
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. Cách đăng ký kỹ năng

Trong planner_agent/agent.py, kỹ năng được tải từ thư mục và thêm vào các công cụ của tác nhân. Đây là giao diện của mã:

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. Kiểm thử tác nhân

Bắt đầu tác nhân cục bộ:

uv run adk run planner_agent

Đặt câu hỏi về quy tắc của thành phố: [user]: What are the rules for running a race on the Las Vegas strip? (Các quy tắc để tổ chức một cuộc đua trên đường Las Vegas là gì?)

Tác nhân sẽ gọi công cụ get_local_and_traffic_rules, thực hiện tìm kiếm vectơ trong AlloyDB và trả về câu trả lời dựa trên các đoạn quy tắc chính thức do Spark xử lý.

11. Triển khai tác nhân

Triển khai lên Nền tảng tác nhân

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

12. Dọn dẹp

Để tránh bị tính phí liên tục, hãy xoá các tài nguyên được tạo trong lớp học lập trình này.

Xoá cụm AlloyDB

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

Xoá ứng dụng thời gian chạy của tác nhân

Bạn có thể xoá thực thể Công cụ suy luận thông qua bảng điều khiển hoặc bằng lệnh gcloud (nếu bạn có tên tài nguyên). Để đơn giản, hãy sử dụng bảng điều khiển:

Chuyển đến trang Agent Runtime (Thời gian chạy của tác nhân).
Chọn planner_agent -> nhấp vào nút ba dấu chấm ở bên phải.
Nhấp vào Xoá.

13. Xin chúc mừng

Xin chúc mừng! Bạn đã nâng cấp thành công một tác nhân ADK với các tính năng nâng cao về bộ nhớ và liên kết dữ liệu thực tế.

Kiến thức bạn học được

Tác nhân có trạng thái: Tích hợp Phiên trên Nền tảng tác nhân để duy trì ngữ cảnh cuộc trò chuyện.
Học tập dài hạn: Đính kèm Ngân hàng bộ nhớ của Nền tảng tác nhân để cho phép tác nhân học hỏi từ các lượt tương tác của người dùng.
Nhập dữ liệu: Sử dụng Công cụ Spark Lightning và Document AI để xử lý các tài liệu không có cấu trúc.
RAG: Xây dựng hệ thống tìm kiếm vectơ trong AlloyDB để căn cứ vào tác nhân trong các quy tắc thực tế.

Các bước tiếp theo

Khám phá tài liệu về Nền tảng tác nhân để tìm hiểu thêm về quá trình triển khai được quản lý.
Nghiên cứu chuyên sâu về tính năng Tìm kiếm vectơ của AlloyDB để biết các mẫu RAG nâng cao.
Mở rộng quy mô quy trình nhập bằng Dataproc Serverless.