Следующая основная презентация для разработчиков ‘26: Улучшение работы агентов с использованием памяти.

1. Введение

В этом практическом занятии вы выведете своих агентов ADK на новый уровень, добавив постоянные и специализированные знания. Вы научитесь управлять состоянием диалога с помощью сессий платформы агентов, обеспечивать долговременное обучение с помощью банка памяти и интегрировать сложные данные о городских правилах, используя Spark и AlloyDB для RAG (генерация с дополненным извлечением).

Что вы будете делать

  • Настройте сеансы платформы агента для сохранения переписки.
  • Внедрить банк памяти , позволяющий агентам учиться на основе предыдущих взаимодействий.
  • Используйте Spark Lightning Engine для загрузки и обработки документации по городским правилам.
  • Создайте систему RAG , используя AlloyDB и векторный поиск.
  • Разверните улучшенный агент на платформе агентов.

Что вам понадобится

Ориентировочная продолжительность: 60 минут

Стоимость ресурсов, созданных в рамках этого практического занятия, должна составлять менее 5 долларов.

2. Прежде чем начать

Создайте проект в Google Cloud.

  1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .
  2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .

Запустить Cloud Shell

Cloud Shell — это среда командной строки, работающая в Google Cloud и поставляемая с предустановленными необходимыми инструментами.

  1. В верхней части консоли Google Cloud нажмите кнопку «Активировать Cloud Shell» .
  2. После подключения к Cloud Shell подтвердите свою аутентификацию: 
    gcloud auth list
  3. Убедитесь, что ваш проект настроен: 
    gcloud config get project
  4. Если параметры вашего проекта заданы не так, как ожидалось, настройте их следующим образом: 
    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

3. Настройте свою среду.

Для выполнения этого практического задания вы будете использовать предварительно настроенную среду в репозитории Keynote.

  1. Клонируйте репозиторий и перейдите в папку проекта: 
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/enhancing-agents-with-memory
  1. Настройте виртуальное окружение Python и установите необходимые пакеты ADK: 
uv venv
source .venv/bin/activate
uv sync

Настройка переменных среды

Для подключения к Agent Platform и AlloyDB агенту требуется определенная конфигурация.

  1. Скопируйте пример файла среды: 
cp .env.example .env
  1. Откройте файл .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
  1. Запустите следующий вспомогательный скрипт, чтобы создать экземпляр 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

4. Создайте агента с помощью функции управления сессиями.

На этом шаге вы инициализируете агента Marathon Planner , который сможет сохранять историю диалогов на протяжении нескольких ходов. Это достигается с помощью класса ADK App и сессий платформы агентов .

Инициализируйте службу агента и службу сессий.

Откройте 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
)

5. Обеспечение долговременного обучения с помощью банка памяти.

В то время как управление сессиями отслеживает отдельные разговоры, то же самое можно сделать и для долговременной памяти. На этом этапе вы подключите агента к Memory Bank платформы Agent Platform — готовой к использованию в корпоративной среде и полностью управляемой службе памяти.

Инициализация службы банка памяти

Функция Memory Bank позволяет агенту восстанавливать контекст между различными сессиями. Обновите файл 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 . Эта функция запускается после того, как агент завершает ответ, позволяя ему «обработать» сессию и сохранить соответствующие данные в банке памяти.

  1. Определите функцию обратного вызова: 
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. Привяжите функцию обратного вызова к LlmAgent : 
root_agent = LlmAgent(
    # ... other params
    after_agent_callback=[auto_save_memories],
)

6. Настройка AlloyDB для RAG

Прежде чем мы сможем загрузить данные о городских правилах, нам потребуется высокопроизводительная база данных для их хранения. На этом этапе вы создадите кластер AlloyDB и инициализируете схему базы данных для векторного поиска.

1. Создайте кластер 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

2. Для получения гранта требуются роли 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

3. Создание базы данных и таблиц с помощью AlloyDB Studio

Поскольку базы данных и таблицы AlloyDB управляются с помощью SQL, для завершения настройки схемы мы будем использовать AlloyDB Studio в консоли Google Cloud.

  1. Перейдите в AlloyDB > Clusters и нажмите rules-db .
  2. В левом навигационном меню нажмите AlloyDB Studio .
  3. Войдите в систему, используя пользователя postgres и установленный вами пароль ( postgres ).
  4. Выполните следующий SQL-запрос для создания базы данных: 
    CREATE DATABASE city_rules;
  5. В 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";

7. Загрузка данных о городских правилах с помощью Spark Lightning Engine.

Для обеспечения действительно точного планирования агенту требуется не просто хорошо составленное подсказка, а знание данных и организационного контекста. На этом этапе вы будете использовать Spark Lightning Engine на Dataproc Serverless для обработки больших PDF-файлов с правилами города и их загрузки в AlloyDB.

Почему именно двигатель Spark Lightning Engine?

Для масштабируемой работы агентов требуется обработка огромных объемов неструктурированных данных. Spark Lightning Engine — это высокопроизводительный механизм выполнения для Spark, который значительно ускоряет эти рабочие нагрузки. Здесь мы используем его для семантического сегментирования документов с помощью Google Document AI .

Изучите Spark Pipeline

Логика обработки данных определена в файле spark-setup/spark_alloydb_processor.py . Конвейер обработки данных включает следующие шаги:

  1. Список PDF-файлов : Извлекает URI документов из хранилища Google Cloud Storage.
  2. Семантическое извлечение : Использует пользовательскую функцию (UDF) для вызова API Document AI.
  3. Запись в AlloyDB : Сохраняет извлеченные фрагменты текста в таблицу AlloyDB с именем 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()

Запустите задание загрузки

Запустите процесс загрузки данных, используя предоставленный скрипт: 

./spark-setup/run_dataproc.sh

8. RAG с AlloyDB

Теперь, когда данные о правилах города находятся в AlloyDB, агент может использовать их для выполнения генерации с расширенным извлечением (Retrieval-Augmented Generation, 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.

  1. Определите инструмент в planner_agent/tools.py , используя шаблон "Hybrid Recall". Для подключения к управляемому серверу AlloyDB MCP мы будем использовать протокол streamable_http : 
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. Зарегистрируйте инструмент и завершите работу над 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. Экспертная помощь в освоении навыков агента.

Навыки агентов — это самодостаточные модули, предоставляющие конкретные инструкции, рекомендации и ресурсы, помогающие агентам более эффективно выполнять задачи. Вместо того чтобы загромождать командную строку сложной инструкцией для каждого инструмента, вы можете объединить эти знания в один навык, который загружается только тогда, когда это необходимо.

Google предоставляет готовые навыки для продуктов Google (таких как AlloyDB и BigQuery), чтобы ваши агенты соответствовали лучшим отраслевым практикам запросов к данным и управления ресурсами. Вы можете изучить эти и другие специализированные шаблоны в Google Skills Depot . Базовые навыки для AlloyDB вы найдете здесь .

1. Изучите файл навыков.

Откройте предварительно настроенный файл навыков по адресу 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.

2. Как регистрируется навык

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

10. Протестируйте агента.

  1. Запустите агент локально: 
uv run adk run planner_agent
  1. Задайте вопрос о городских правилах: [user]: What are the rules for running a race on the Las Vegas strip?

Агент вызовет инструмент get_local_and_traffic_rules , выполнит векторный поиск в AlloyDB и вернет ответ, основанный на официальных блоках правил, обработанных Spark.

11. Разверните агента.

Развернуть на платформе агента 

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

12. Уборка

Во избежание дальнейших списаний средств удалите ресурсы, созданные в ходе этого практического занятия.

Удалите кластер AlloyDB. 

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

Удалите приложение Agent Runtime.

Удалить экземпляр Reasoning Engine можно через консоль или с помощью команды gcloud (если известно имя ресурса). Для простоты используйте консоль:

  1. Перейдите на страницу "Среда выполнения агента" .
  2. Выберите planner_agent –> нажмите кнопку с тремя точками справа.
  3. Нажмите «Удалить» .

13. Поздравляем!

Поздравляем! Вы успешно расширили возможности агента ADK, добавив расширенные функции привязки памяти и данных.

Что вы узнали

  • Агенты с сохранением состояния : интеграция сессий платформы агентов для поддержания контекста разговора.
  • Долгосрочное обучение : Подключение банка памяти агентской платформы , позволяющего агенту обучаться на основе взаимодействия с пользователем.
  • Ввод данных : использование Spark Lightning Engine и Document AI для обработки неструктурированных документов.
  • RAG : Создание системы векторного поиска в AlloyDB для привязки агента к правилам реального мира.

Следующие шаги