1. Giới thiệu
Trong lớp học lập trình này, bạn sẽ nâng cấp các tác nhân ADK bằng cách thêm kiến thức chuyên biệt và kiến thức liên tục. Bạn sẽ tìm hiểu cách quản lý trạng thái cuộc trò chuyện bằng Nền tảng phiên của 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 phức tạp về quy tắc 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 dành cho nhân viên hỗ trợ để duy trì cuộc trò chuyện.
- Triển khai Ngân hàng bộ nhớ để cho phép các tác nhân học hỏi từ những lần tương tác trước.
- Sử dụng Spark Lightning Engine để nhập và xử lý tài liệu về các 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 cho 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 chọn dự án, hãy chọn hoặc tạo một dự án trên đám mây của Google Cloud.
- Đảm bảo 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ó được bật trong một dự án hay không.
Khởi động Cloud Shell
Cloud Shell là một môi trường dòng lệnh chạy trong Google Cloud và đượ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 Cloud Console.
- Sau khi kết nối với Cloud Shell, hãy xác minh thông tin xác thực của bạn:
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 không đượ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
Đặt 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ữ khoá.
- Sao chép 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 này 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ở
.envrồi 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 đây để tạo một thực thể Agent Engine sẽ được 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_IDvào tệp.envcủa bạn:
uv run utils/setup_agent_engine.py
Sau khi thực hiện 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
Trong bước này, bạn sẽ khởi tạo một Marathon Planner Agent (Trợ lý 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ể đạt được điều này bằng cách sử dụng lớp App ADK và Phiên nền tảng tác nhân.
Khởi động 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 của 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 các tác nhân theo thời gian và sửa đổi bối 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 từng cuộc trò chuyện, bạn có thể làm điều 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ý hoàn toàn và sẵn sàng cho doanh nghiệp.
Khởi động Dịch vụ ngân hàng bộ nhớ
Memory Bank 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 dữ liệu vào bộ nhớ
Để đảm bảo tác nhân học hỏi từ mọi lượt tương tác, chúng ta sẽ thêm một after_agent_callback. Hàm này được kích hoạt sau khi tác nhân hoàn tất một phản hồi, cho phép tác nhân "tiêu hoá" phiên và lưu những thông tin liên quan vào bộ nhớ.
- 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ể thu thậ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 đó. Trong bước này, bạn sẽ tạo một cụm AlloyDB và khởi động lược đồ cơ sở dữ liệu để 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à phiên bản 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ủ MCP AlloyDB đượ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 sau để 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 giản đồ.
- Chuyển đến AlloyDB > Cụm rồi nhấp vào
rules-db. - Trong trình đơn điều hướng 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 của bạn sang
city_rulestrong AlloyDB Studio và chạy SQL sau đây để cài đặt các tiện ích cũng như tạo bảngrules:-- 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 về quy tắc của thành phố bằng Spark Lightning Engine
Để 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 tạo ra một cách khéo léo; tác nhân cần căn cứ vào dữ liệu và bối cảnh của tổ chức. Trong bước này, bạn sẽ sử dụng Spark Lightning Engine 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 đó vào AlloyDB.
Tại sao nên dùng Spark Lightning Engine?
Để có thể tiếp cận các tác nhân ở quy mô lớn, bạn cần xử lý một lượng lớn dữ liệu không có cấu trúc. Spark Lightning Engine 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ẽ sử dụng công cụ nà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á Spark Pipeline
Logic truyền nhận được xác định trong spark-setup/spark_alloydb_processor.py. Quy trình này tuân theo các bước sau:
- Liệt kê tệp PDF: Truy xuất URI tài liệu từ một bộ chứa Google Cloud Storage.
- 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.
- Ghi vào AlloyDB: Lưu các đoạn văn bản đã trích xuất vào bảng
rulescó tên trong AlloyDB.
# 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 lệnh truyền dẫn
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 về quy tắc của thành phố đã có 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 giúp đả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 có khả năng tìm kiếm vectơ vượt trội, cho phép chúng tôi lưu trữ cả dữ liệu có cấu trúc và các bản 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 sẵn trong AlloyDB để tìm thông tin quy tắc phù hợp nhất.
Tính năng Hybrid Recall (Tìm lại kết hợp) với 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 cách sử dụ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 các quy tắc tại địa phương bằng công cụ RAG
Để cung cấp công cụ này cho tác nhân, bạn phải xác định công cụ đó trong planner_agent/tools.py rồi đăng ký trong planner_agent/agent.py. Chúng ta sẽ sử dụng máy chủ MCP AlloyDB từ xa được quản lý của Google Cloud để kết nối với cơ sở dữ liệu.
- Xác định công cụ trong
planner_agent/tools.pybằng cách sử dụng mẫu "Hybrid Recall". Chúng ta sẽ sử dụng giao thứcstreamable_httpđể kết nối với máy chủ MCP AlloyDB đượ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 về kỹ năng của nhân viên hỗ trợ
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 nhiệm vụ hiệu quả hơn. Thay vì làm rối lời nhắc hệ thống bằng các hướng dẫn phức tạp cho từng công cụ, bạn có thể đóng gói chuyên môn đó vào 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 các đặc vụ của bạn tuân thủ các phương pháp hay nhất trong ngành về việc truy vấn dữ liệu và quản lý tài nguyên. Bạn có thể khám phá những mẫu này và các mẫu chuyên biệt khác tại Google Skills Depot. Bạn sẽ tìm thấy các kỹ năng cơ bản về 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. Dưới đây là ví dụ minh hoạ:
---
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 này được tải từ thư mục và thêm vào các công cụ của tác nhân. Sau đâ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
- Khởi động 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?
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 khối quy tắc chính thức do Spark xử lý.
11. Triển khai tác nhân
Triển khai trê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 bạn đã 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á phiên bản Reasoning Engine thông qua bảng điều khiển hoặc bằng cách sử dụng lệnh gcloud (nếu có tên tài nguyên). Để đơn giản hoá, hãy sử dụng bảng điều khiển:
- Chuyển đến trang 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 Xóa.
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 bằng các chức năng nâng cao về bộ nhớ và dữ liệu cơ sở.
Kiến thức bạn học được
- Stateful Agents: Tích hợp Agent Platform Sessions để duy trì bối 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 hoạt động tương tác của người dùng.
- Nhập dữ liệu: Sử dụng Spark Lightning Engine và Document AI để xử lý các tài liệu không có cấu trúc.
- RAG: Xây dựng một hệ thống tìm kiếm vectơ trong AlloyDB để đặt nền tảng cho tác nhân theo các quy tắc trong thế giới thực.
Các bước tiếp theo
- Khám phá tài liệu về Nền tảng đại lý để tìm hiểu thêm về việc 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 cho các mẫu RAG nâng cao.
- Mở rộng quy mô các quy trình truyền dữ liệu bằng Dataproc Serverless.