این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

سخنرانی کلیدی بعدی توسعه‌دهندگان در سال 2026: تقویت عامل‌ها با حافظه

۱. مقدمه

در این آزمایشگاه کد، شما با افزودن دانش مداوم و تخصصی، عامل‌های ADK خود را به سطح بعدی خواهید برد. شما یاد خواهید گرفت که چگونه وضعیت مکالمه را با جلسات پلتفرم عامل مدیریت کنید، یادگیری بلندمدت را با بانک حافظه فعال کنید و داده‌های قوانین پیچیده شهری را با استفاده از Spark و AlloyDB برای RAG (بازیابی-تولید افزوده) ادغام کنید.

کاری که انجام خواهید داد

جلسات پلتفرم عامل را برای تداوم مکالمه پیکربندی کنید.
یک بانک حافظه پیاده‌سازی کنید تا به عامل‌ها اجازه دهید از تعاملات قبلی درس بگیرند.
از موتور Spark Lightning برای دریافت و پردازش اسناد قوانین شهری استفاده کنید.
ساخت یک سیستم RAG با استفاده از AlloyDB و جستجوی برداری
عامل بهبود یافته را در Agent Platform مستقر کنید.

آنچه نیاز دارید

یک مرورگر وب مانند کروم
یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
آشنایی اولیه با پایتون و SQL

مدت زمان تخمینی: ۶۰ دقیقه

منابع ایجاد شده در این آزمایشگاه کد باید کمتر از ۵ دلار هزینه داشته باشند.

۲. قبل از شروع

ایجاد یک پروژه ابری گوگل

در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

شروع پوسته ابری

Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم از قبل روی آن بارگذاری شده‌اند.

روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
پس از اتصال به Cloud Shell، احراز هویت خود را تأیید کنید:
```
gcloud auth list
```
تأیید کنید که پروژه شما پیکربندی شده است:
```
gcloud config get project
```
اگر پروژه شما مطابق انتظار تنظیم نشده است، آن را تنظیم کنید:
```
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
```

تأیید اعتبار:

gcloud auth list

پروژه خود را تایید کنید:

gcloud config get project

در صورت نیاز آن را تنظیم کنید:

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

فعال کردن APIها

این دستور را اجرا کنید تا تمام API های مورد نیاز برای مدیریت جلسه، پردازش Spark و 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

۳. محیط خود را آماده کنید

برای این آزمایشگاه کد، از محیط از پیش پیکربندی‌شده در مخزن اصلی استفاده خواهید کرد.

مخزن را کلون کنید و به پوشه پروژه بروید:

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

یک محیط مجازی پایتون راه‌اندازی کنید و بسته‌های ADK مورد نیاز را نصب کنید:

uv venv
source .venv/bin/activate
uv sync

پیکربندی متغیرهای محیطی

این عامل برای اتصال به Agent Platform و AlloyDB به پیکربندی خاصی نیاز دارد.

فایل محیط نمونه را کپی کنید:

cp .env.example .env

فایل .env را باز کنید و فیلدهای زیر را به‌روزرسانی کنید:
- GOOGLE_CLOUD_PROJECT : شناسه پروژه شما.
- 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

اسکریپت کمکی زیر را اجرا کنید تا یک نمونه از Agent Engine ایجاد شود که برای جلسات مکالمه و حافظه بلندمدت استفاده شود. این کار به طور خودکار AGENT_ENGINE_ID را در فایل .env شما پر می‌کند:

uv run utils/setup_agent_engine.py

پس از موفقیت، باید موارد زیر را ببینید:

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

۴. ایجاد یک عامل با مدیریت جلسه

در این مرحله، شما یک عامل برنامه‌ریز ماراتون راه‌اندازی خواهید کرد که می‌تواند تاریخچه مکالمات را در چندین نوبت حفظ کند. این کار با استفاده از کلاس ADK App و Agent Platform Sessions انجام می‌شود.

سرویس Agent و Session را مقداردهی اولیه کنید

planner_agent/agent.py را باز کنید. خواهید دید که چگونه یک کلاس ADK برای ادغام جلسات پلتفرم عامل اضافه می‌کنیم. این به ما این امکان را می‌دهد که عامل‌های خود را به مرور زمان دارای وضعیت کنیم و در صورت نیاز، زمینه را تغییر دهیم.

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
)

۵. با بانک حافظه، یادگیری بلندمدت را فعال کنید

در حالی که مدیریت جلسه مکالمات فردی را ردیابی می‌کند، می‌توانید همین کار را برای حافظه بلندمدت انجام دهید. در این مرحله، شما عامل را به بانک حافظه پلتفرم عامل ، یک سرویس حافظه آماده و کاملاً مدیریت‌شده، متصل خواهید کرد.

سرویس بانک حافظه را مقداردهی اولیه کنید

بانک حافظه به عامل اجازه می‌دهد تا زمینه را در جلسات مختلف فراخوانی کند. planner_agent/agent.py را به‌روزرسانی کنید تا سرویس حافظه را نیز شامل شود:

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
    )

پیاده‌سازی خودکار حافظه ورودی

برای اطمینان از اینکه عامل از هر نوبت یاد می‌گیرد، یک after_agent_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
        )

تابع callback را به LlmAgent پیوست کنید:

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

۶. راه‌اندازی AlloyDB برای RAG

قبل از اینکه بتوانیم داده‌های قوانین شهر را دریافت کنیم، به یک پایگاه داده با کارایی بالا برای ذخیره آن نیاز داریم. در این مرحله، شما یک خوشه AlloyDB ایجاد خواهید کرد و طرح پایگاه داده را برای جستجوی برداری مقداردهی اولیه خواهید کرد.

۱. ایجاد کلاستر AlloyDB و نمونه اولیه

برای ایجاد کلاستر و نمونه اصلی آن، این دستورات را در Cloud Shell اجرا کنید:

# 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

۲. اعطای نقش‌های مورد نیاز IAM

برای استفاده از سرور مدیریت‌شده AlloyDB MCP، هویت شما به مجوزهای خاصی نیاز دارد. برای اعطای نقش‌های مورد نیاز، این دستورات را اجرا کنید:

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

۳. ایجاد پایگاه داده و جداول از طریق AlloyDB Studio

از آنجایی که پایگاه‌های داده و جداول AlloyDB از طریق SQL مدیریت می‌شوند، ما از AlloyDB Studio در کنسول Google Cloud برای نهایی کردن طرحواره استفاده خواهیم کرد.

به AlloyDB > Clusters بروید و روی rules-db کلیک کنید.
در منوی ناوبری سمت چپ، روی AlloyDB Studio کلیک کنید.
با استفاده از نام کاربری postgres و رمز عبوری که تنظیم کرده‌اید ( postgres ) وارد سیستم شوید.
برای ایجاد پایگاه داده، SQL زیر را اجرا کنید:
```
CREATE DATABASE city_rules;
```

اتصال پایگاه داده خود را در AlloyDB Studio به city_rules تغییر دهید و SQL زیر را برای نصب افزونه‌ها و ایجاد جدول 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";

۷. دریافت داده‌های قوانین شهر با موتور Spark Lightning

برای ارائه برنامه‌ریزی واقعاً دقیق، یک عامل به چیزی بیش از یک دستورالعمل خوش‌ساخت نیاز دارد؛ بلکه به پایه‌گذاری داده‌ها و زمینه سازمانی نیز نیاز دارد. در این مرحله، شما از موتور Spark Lightning در Dataproc Serverless برای پردازش PDFهای قوانین شهرهای بزرگ و وارد کردن آنها به AlloyDB استفاده خواهید کرد.

چرا موتور Spark Lightning؟

عوامل زمینی در مقیاس بزرگ نیاز به پردازش حجم عظیمی از داده‌های بدون ساختار دارند. موتور لایتنینگ اسپارک یک موتور اجرایی با کارایی بالا برای اسپارک است که این حجم کار را به طور قابل توجهی تسریع می‌کند. ما در اینجا از آن برای انجام قطعه‌بندی معنایی روی اسناد با استفاده از هوش مصنوعی اسناد گوگل استفاده می‌کنیم.

خط لوله اسپارک را کاوش کنید

منطق مصرف در spark-setup/spark_alloydb_processor.py تعریف شده است. این خط لوله مراحل زیر را دنبال می‌کند:

فهرست فایل‌های PDF : آدرس‌های اینترنتی (URI) سند را از مخزن ذخیره‌سازی ابری گوگل بازیابی می‌کند.
استخراج معنایی : از یک UDF (تابع تعریف‌شده توسط کاربر) برای فراخوانی API هوش مصنوعی سند استفاده می‌کند.
نوشتن در AlloyDB : تکه‌های متن استخراج‌شده را در جدولی به نام rules در 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()

اجرای عملیات بلع

فرآیند مصرف را با استفاده از اسکریپت ارائه شده فعال کنید:

./spark-setup/run_dataproc.sh

۸. RAG با AlloyDB

اکنون که داده‌های قوانین شهری در AlloyDB قرار دارد، عامل می‌تواند از آن برای انجام بازیابی-تقویت تولید (RAG) استفاده کند. این امر تضمین می‌کند که طرح ماراتن به کدهای خاص شهر پایبند باشد.

قدرت AlloyDB برای RAG

AlloyDB در جستجوی برداری برتری دارد و به ما امکان می‌دهد هم داده‌های ساختاریافته و هم جاسازی‌های برداری را در یک مکان ذخیره کنیم. عامل می‌تواند از تابع embedding داخلی در AlloyDB برای یافتن مرتبط‌ترین اطلاعات قوانین استفاده کند.

فراخوانی ترکیبی با جستجوی برداری

برای دسترسی عامل به این داده‌ها، ابزاری ارائه می‌دهیم که با استفاده از شباهت برداری، AlloyDB را پرس‌وجو می‌کند. می‌توانید این منطق را در hybrid_recall.sql مشاهده کنید که نحوه محاسبه فاصله بین یک پرس‌وجو و قوانین ذخیره شده ما را نشان می‌دهد:

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، عامل را در قوانین محلی قرار دهید

برای اینکه این ابزار در دسترس عامل قرار گیرد، باید آن را در planner_agent/tools.py تعریف کنید و سپس آن را در planner_agent/agent.py ثبت کنید. ما از سرور مدیریت‌شده‌ی AlloyDB MCP از Google Cloud برای اتصال به پایگاه داده‌ی خود استفاده خواهیم کرد.

ابزار را در planner_agent/tools.py با استفاده از الگوی "Hybrid Recall" تعریف کنید. ما از پروتکل streamable_http برای اتصال به سرور مدیریت‌شده AlloyDB MCP استفاده خواهیم کرد:

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

ابزار را ثبت کنید و 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
)

۹. راهنمایی تخصصی با مهارت‌های کارشناس

مهارت‌های عامل، ماژول‌های مستقلی هستند که دستورالعمل‌ها، راهنمایی‌ها و منابع خاصی را برای کمک به عامل‌ها در انجام مؤثرتر وظایف ارائه می‌دهند. به جای اینکه سیستم خود را با دستورالعمل‌های پیچیده برای هر ابزار شلوغ کنید، می‌توانید آن تخصص را در یک مهارت خلاصه کنید که فقط در صورت نیاز بارگذاری می‌شود.

گوگل مهارت‌های از پیش ساخته شده‌ای را برای محصولات گوگل (مانند AlloyDB و BigQuery) ارائه می‌دهد تا اطمینان حاصل شود که نمایندگان شما از بهترین شیوه‌های صنعتی برای پرس‌وجوی داده‌ها و مدیریت منابع پیروی می‌کنند. می‌توانید این الگوها و سایر الگوهای تخصصی را در Google Skills Depot بررسی کنید. مهارت‌های پایه AlloyDB را اینجا خواهید یافت.

۱. فایل مهارت‌ها را بررسی کنید

فایل مهارت از پیش پیکربندی شده را در planner_agent/skills/get-local-and-traffic-rules/SKILL.md باز کنید. این چیزی است که به نظر می‌رسد:

---
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.

۲. نحوه ثبت مهارت

در planner_agent/agent.py ، مهارت از دایرکتوری بارگذاری شده و به ابزارهای عامل اضافه می‌شود. کد به این صورت است:

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

۱۰. تست عامل

عامل را به صورت محلی شروع کنید:

uv run adk run planner_agent

سوالی در مورد قوانین شهر بپرسید: [user]: What are the rules for running a race on the Las Vegas strip?

عامل، ابزار get_local_and_traffic_rules را فراخوانی می‌کند، یک جستجوی برداری در AlloyDB انجام می‌دهد و پاسخی را بر اساس تکه‌های رسمی قوانین پردازش شده توسط Spark برمی‌گرداند.

۱۱. عامل را مستقر کنید

استقرار در پلتفرم Agent

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

۱۲. تمیز کردن

برای جلوگیری از هزینه‌های جاری، منابع ایجاد شده در طول این آزمایش کد را حذف کنید.

خوشه AlloyDB را حذف کنید

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

برنامه زمان اجرای Agent را حذف کنید

می‌توانید نمونه Reasoning Engine را از طریق کنسول یا با استفاده از دستور gcloud (در صورت داشتن نام منبع) حذف کنید. برای سادگی، از کنسول استفاده کنید:

به صفحه زمان اجرای عامل بروید.
planner_agent را انتخاب کنید -> روی دکمه سه نقطه در سمت راست کلیک کنید.
روی حذف کلیک کنید.

۱۳. تبریک

تبریک! شما با موفقیت یک عامل ADK را با قابلیت‌های پیشرفته حافظه و داده‌کاوی ارتقا دادید.

آنچه آموخته‌اید

عامل‌های دارای وضعیت : ادغام جلسات پلتفرم عامل برای حفظ زمینه مکالمه.
یادگیری بلندمدت : اتصال یک بانک حافظه پلتفرم عامل برای اینکه عامل بتواند از تعاملات کاربر یاد بگیرد.
دریافت داده‌ها : استفاده از موتور Spark Lightning و هوش مصنوعی اسناد برای پردازش اسناد بدون ساختار.
RAG : ساخت یک سیستم جستجوی برداری در AlloyDB برای پایه گذاری عامل در قوانین دنیای واقعی.

مراحل بعدی

برای کسب اطلاعات بیشتر در مورد استقرار مدیریت‌شده، مستندات پلتفرم عامل را بررسی کنید.
برای الگوهای پیشرفته RAG، به جستجوی وکتور AlloyDB عمیق‌تر بپردازید.
خطوط لوله مصرف خود را با Dataproc Serverless مقیاس‌بندی کنید.