Создание персонализированных агентов с помощью ADK, MCP и банка памяти

1. Введение

Современный набор агентов

Для создания агента искусственного интеллекта производственного уровня требуется нечто большее, чем просто большая языковая модель (LLM). Хотя LLM обеспечивает возможности рассуждения, надежный агент должен взаимодействовать с внешним миром, управлять состоянием разговора и запоминать предпочтения пользователя с течением времени.

демо1демо2

На этом семинаре вы научитесь проектировать и создавать комплексную агентную систему, используя три базовые технологии:

  1. Подключение (MCP) : Предоставляет вашему агенту доступ к локальным инструментам и данным.
  2. Оркестрация (ADK) : Для управления циклом рассуждений и состоянием агента.
  3. Память (Банк памяти) : Обеспечение долговременного, персонализированного контекста.

обзор_мастерской

Основные концепции

Компонент

Функция

Протокол контекста модели (MCP)

Универсальный стандарт, который позволяет подключать модели ИИ к внешним системам (базам данных, файловым системам, API) без необходимости создания собственных интеграций.

Комплект для разработки агентов (ADK)

Это платформа, предоставляющая среду выполнения для агентов, управляющая циклом событий, переходами состояний и выполнением инструментов.

Сессионное обслуживание

Обрабатывает кратковременную память . Сохраняет непосредственный контекст разговора (например, «Что только что спросил пользователь?»), но очищается по завершении сессии.

Банк памяти Vertex AI

Обрабатывает долговременную память . Сохраняет специфичные для пользователя данные и предпочтения (например, «Пользователь предпочитает Python») неограниченно долго, позволяя агенту персонализировать будущие взаимодействия.

Vertex AI Agent Engine

Сервис управляемой инфраструктуры, обеспечивающий размещение компонентов логики и памяти ваших агентов в масштабируемом режиме.

Что вы построите

Для демонстрации этих концепций вам предстоит создать помощника по праздничному дизайну . Этот агент сможет обрабатывать сложные запросы пользователей и автономно управлять локальными инструментами Python для генерации персонализированного кода и изображений.

Вы пройдете три этапа:

  1. Слой инструментов : Создайте MCP-сервер для предоставления ИИ доступа к локальным функциям Python.
  2. Уровень агента : Используйте ADK для создания агента, который планирует и выполняет многоэтапные рабочие процессы.
  3. Уровень памяти : Интеграция банка памяти позволяет агенту изучать и запоминать предпочтения пользователя в отношении стиля.

2. Настройка

Для работы наших агентов искусственного интеллекта нам необходимы две вещи: проект Google Cloud, который обеспечит необходимую основу.

Часть первая: Включение платёжного аккаунта

  • Для развертывания вам потребуется пополнить свой платежный аккаунт на 5 долларов. Убедитесь, что вы активировали свою учетную запись Gmail .

Часть вторая: Открытая среда

  1. 👉 Нажмите на эту ссылку, чтобы перейти непосредственно в редактор Cloud Shell.
  2. 👉 Если сегодня вам будет предложено авторизоваться, нажмите «Авторизовать» , чтобы продолжить. Нажмите, чтобы авторизовать Cloud Shell.
  3. 👉 Если терминал не отображается внизу экрана, откройте его:
    • Нажмите «Просмотреть».
    • Нажмите «Терминал» Откройте новый терминал в редакторе Cloud Shell.
  4. 👉💻 В терминале убедитесь, что вы уже авторизованы и что проект настроен на ваш идентификатор проекта, используя следующую команду: 
    gcloud auth list
  5. 👉💻 Клонируйте проект Bootstrap с GitHub: 
    git clone https://github.com/cuppibla/holiday_workshop
  6. 👉💻 Запустите скрипт установки из каталога проекта. 
    cd ~/holiday_workshop
./init.sh
    Скрипт автоматически выполнит остальную часть процесса настройки.
  7. 👉💻 Укажите необходимый идентификатор проекта: 
    gcloud config set project $(cat ~/project_id.txt) --quiet

Часть третья: Настройка прав доступа

  1. 👉💻 Включите необходимые API, используя следующую команду. Это может занять несколько минут. 
    gcloud services enable \
    cloudresourcemanager.googleapis.com \
    servicenetworking.googleapis.com \
    run.googleapis.com \
    aiplatform.googleapis.com \
    compute.googleapis.com
  2. 👉💻 Предоставьте необходимые права доступа, выполнив следующие команды в терминале: 
    . ~/holiday_workshop/set_env.sh

Обратите внимание, что для вас создан файл .env . В нём отображается информация о вашем проекте.

3. Включение MCP

Момент «USB-C» для искусственного интеллекта

Представьте, что каждый раз, покупая новую мышь, вам приходилось бы припаивать её к материнской плате. Таково было положение дел с инструментами искусственного интеллекта до недавнего времени. Разработчикам приходилось писать собственный «связующий код» для подключения LLM к базам данных, файловым системам или API.

Представляем протокол контекста модели (MCP) . Представьте MCP как порт USB-C для приложений искусственного интеллекта . Он обеспечивает стандартизированный способ подключения моделей ИИ к источникам данных и инструментам.

Если вы один раз создадите MCP-сервер для своих инструментов, вы сможете подключить его к Gemini CLI, IDE или любому другому MCP-совместимому клиенту, не изменив ни единой строки кода.

Что вы построите

mcp_server

В этом практическом занятии вы создадите помощника по созданию праздничного дизайна , который будет:

  1. Подключается к вашей локальной среде (инструментам студии) с помощью MCP .
  2. Надежно управляет контекстом диалога с помощью комплекта разработки агентов (ADK) .
  3. Запоминает ваши предпочтения (например, "Я предпочитаю код на Python") в разных сессиях, используя банк памяти Vertex AI .

Построение серверной логики

Мы подготовили среду, но логика сервера еще не завершена. Нам необходимо внедрить четыре конкретных инструмента, которые наш агент в конечном итоге будет использовать для создания нашей поздравительной открытки.

Часть первая: Открытие каркаса сервера

Мы будем работать в директории 01-MCP-Files-Testing/01-starter .

  1. В терминале Cloud Shell убедитесь, что вы находитесь в правильной директории: 
    cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
  2. Откройте файл в редакторе Cloud Shell, выполнив следующую команду: 
    cloudshell edit ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py

Вы заметите, что стандартный код (настройка сервера MCP, обработка соединений и инициализация клиента Vertex AI) уже готов. Однако четыре основные функции в настоящее время представляют собой пустые заполнители.

Часть вторая: Реализация генератора праздничных сцен

Во-первых, нам нужен инструмент, который берет интересы пользователя (например, «птицы») и превращает их в подробную, насыщенную информацией подсказку, оптимизированную для генерации изображений.

Найдите комментарий #REPLACE_GENERATE_HOLIDAY_SCENE внутри функции generate_holiday_scene .

Замените всю эту строку следующим кодом:

    prompt = (
        f"""
        Create a cozy, high-fidelity 3D render of a winter holiday scene.
        The scene should be warm and inviting with soft cinematic lighting.
        
        Seamlessly integrate the following specific theme/interest into the 
        holiday decor or landscape: {interest}.
        
        The style should be whimsical but detailed.
        Aspect Ratio: 16:9 Landscape.
        """
    )
    generate_image(prompt, "16:9", "static/generated_scene.png")
    return "Done! Saved at generated_scene.png"

Часть третья: Реализация окончательного результата фотосъемки

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

Найдите комментарий #REPLACE_GENERATE_FINAL_PHOTO .

Замените всю эту строку следующим кодом, чтобы выполнить окончательную передачу стиля и рендеринг: 

    prompt = (
        """
        Generate a photorealistic close-up shot of a rustic wooden fireplace mantle.
        
        Lighting: Warm, glowing ambient light from a fire below (out of frame).
        Background: Softly blurred (bokeh) pine garland and twinkling lights.
        
        Foreground Composition:
        1. A wooden picture frame containing the [attached selfie image]. 
           The face in the photo must be clearly visible.
        2. A folded holiday greeting card standing upright next to the frame. 
           The front of the card displays the [attached holiday scene image] as a print.
           
        Ensure the perspective is grounded and realistic, as if taken with a 50mm lens.
        """
    )
    generate_image(prompt, "16:9", "static/generated_final_photo.png", ["static/generated_selfie.png", "static/generated_scene.png"])
    return "Done! Saved at generated_final_photo.png"

Настройка среды

Теперь, когда код готов, нам нужно убедиться, что установлены все необходимые зависимости. Мы будем использовать uv — быстрый менеджер пакетов и проектов для Python.

👉💻 В терминале выполните следующую команду, чтобы добавить FastMCP в качестве зависимости нашего проекта: 

cd ~/holiday_workshop/01-MCP-Files-Testing/01-starter/
uv add fastmcp

Вы увидите, что в файл ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml добавлена ​​новая зависимость fastmcp>=2.13.3 .

4. Тестирование с помощью Gemini CLI для MCP Server

Теперь, когда наш серверный код готов, как же его протестировать?

Обычно тестирование бэкэнд-сервера требует создания фронтенд-интерфейса или написания сложных curl запросов. Однако здесь мы можем использовать Gemini CLI .

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

Подключайся и работай

Мы укажем Gemini CLI управлять нашим сервером с помощью команды mcp add .

В терминале выполните следующую команду: 

gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py
  • add holidays : Мы дали нашему серверу прозвище ("праздники").
  • uv run ... : Мы предоставили явную команду для запуска только что модифицированного нами Python-сервера.

Давайте творить волшебство!

Теперь начнём сеанс чата: 

gemini

Попробуйте ввести следующую команду, чтобы проверить, видит ли Gemini ваши новые инструменты. Обратите внимание, что вам может потребоваться разрешить Gemini CLI использовать наш инструмент для работы с праздниками.

  • 👉 Пользователь: 
    "I want to create a festive holiday photo. I like birds a lot."
  • Близнецы: 
    *Thinking...*
*Calling tool: generate_holiday_scene(interest='birds')*

Done! Saved at generated_scene.png
  • 👉 Пользователь: 
    "Great! Now generate a knitting pattern for a sweater with reindeer on it."
  • Близнецы:
    *Thinking...*
*Calling tool: generate_sweater_pattern(motif='reindeer')*

Done! Saved at generated_pattern.png
    Благодаря использованию MCP, ИИ точно понял, какую функцию Python нужно вызвать для выполнения вашего запроса!

Рассмотрите изображение.

  • Завершите работу Gemini CLI, нажав Control+C .
  • Проверьте сгенерированное изображение в вашей папке: ~/holiday_workshop/01-MCP-Files-Testing/01-starter/static .

Просмотрите свою фотографию здесь:

Заключение и дальнейшие шаги

Поздравляем! Вы успешно создали работающий сервер MCP. Теперь у вас есть функциональный набор «инструментов ИИ», способных генерировать шаблоны, компоновать изображения и уточнять сцены.

Однако, вы заметили что-нибудь в приведенном выше тесте? Вам нужно было управлять процессом. Вам нужно было сначала запросить сцену, затем запросить шаблон, а затем запросить их объединение.

Хотя Gemini — это интеллектуальная система, для сложного производственного процесса, где нам нужно сначала создать узор, прежде чем нанести его на свитер, и обрабатывать ошибки, если генерация изображения не удалась, нам нужен больший контроль. Нам нужна специализированная система, которая сможет планировать, анализировать свою работу и управлять состоянием нашей поздравительной открытки без нашего постоянного контроля на каждом этапе.

В следующем разделе мы наведём порядок в этом творческом хаосе. Мы собираемся использовать комплект разработки агентов (ADK) для создания структурированного агента, который будет координировать работу этих инструментов MCP, создавая идеальный производственный конвейер.

5. Создание агента ADK с помощью Vibe-кодирования

У нас есть рабочий набор инструментов (наш MCP-сервер), но в настоящее время всю основную работу выполняют мы сами — точно указываем Gemini, какой инструмент использовать и когда.

В этом разделе мы создадим агента искусственного интеллекта : систему, способную рассуждать, планировать и автономно выполнять многоэтапные задачи. Для этого мы будем использовать комплект разработки агентов (ADK) .

agent_mcp

Что такое агент?

Если инструменты MCP — это «руки» (выполняющие работу), то Агент — это «мозг». Агент использует LLM, чтобы понять намерение пользователя («Сделай мне поздравительную открытку»), разбивает его на этапы («Сначала мне нужна сцена, потом шаблон...») и решает, какие инструменты использовать для достижения цели.

Что такое ADK?

Комплект разработки агентов (ADK) — это фреймворк от Google, который упрощает создание таких агентов. Он берет на себя сложную «инфраструктуру», такую ​​как управление историей чата, подключение к инструментам и переключение между различными моделями, — поэтому вы можете сосредоточиться на характере и логике вашего приложения.

Кодирование атмосферы на основе контекста

Распространенная практика — использовать один большой запрос для генерации кода. Однако при разработке сложных приложений зачастую лучше рассматривать ИИ как партнера, который поддерживает контекст во времени.

Мы воспользуемся функциями работы с памятью в Gemini CLI, чтобы подготовиться, прежде чем напишем хотя бы одну строку кода.

1. Подготовка окружающей среды

Откройте терминал и перейдите в директорию starter: 

cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter

Запустите Gemini CLI: 

gemini

2. Управление контекстом и памятью

При создании вибрационного кода ИИ необходимо знать, кто он и что он знает. Gemini CLI позволяет нам явно управлять этим.

  • /memory show : Введите это, чтобы увидеть, что в данный момент известно ИИ о вашем проекте и сессии.
  • /memory add : Используйте эту команду для внедрения базовых знаний, которые ИИ должен помнить на протяжении всего разговора.

Начнём с определения профиля нашего партнёра по программированию. Выполните следующую команду в Gemini CLI: 

/memory add "You are an expert Python developer specialized in the Google Agent Development Kit (ADK). You write clean, modular code and prefer using the latest ADK patterns."

Теперь Gemini понимает свою роль. Этот контекст будет влиять на каждый последующий ответ, обеспечивая высокое качество кода, соответствующего требованиям ADK.

3. Шаг 1: Вибрационное кодирование базового агента.

Вместо того чтобы пытаться создать всю систему сразу, давайте начнём с каркаса. Мы хотим установить файловую структуру и базовую личность агента.

Введите следующую команду в командную строку Gemini: 

Let's start by building the basic agent structure. 

Please create a file structure for a `root_agent`. 
1. Create `root_agent/__init__.py` that imports `agent`.
2. Create `root_agent/agent.py` by following exactly how this file is doing import and agent creation @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Create an `Agent` named "root_agent" using the model "gemini-2.5-flash".
- The instruction string should define a "Holiday Magic Assistant". 
- The personality should be enthusiastic (`🎄✨`) and prefer "cute, kawaii, cartoon" styles for any visual tasks.

Gemini сгенерирует структуру файлов и исходный код на Python. Проверьте его, чтобы убедиться в правильности, затем примените/примите изменения.

4. Шаг 2: Добавление сервера MCP (Инструменты)

Теперь, когда у нас есть базовый агент, нам нужно дать ему «руководить». Нам нужно подключить агента к серверу MCP, который мы создали в предыдущей лабораторной работе.

Введите следующую команду в командную строку Gemini: 

Now, let's give the agent access to tools. Update `agent.py` to include our local MCP server. By following exactly how this agent is connecting to mcp tool @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py

In `agent.py`:
- Import `McpToolset` to define our STDIO MCP server. as @~/holiday_workshop/02-Vibe-Coding-ADK-Agent/01-starter/agent_reference.py
- Connect to the python file located at `../mcp_server.py` relative to agent.py.

Теперь Gemini переработает ваш существующий agent.py , чтобы включить в него определения инструментов и логику подключения.

Примечание: Если вы хотите проверить свою работу или если сгенерированный код работает не так, как ожидалось, вы можете сравнить свои файлы с эталонным решением, расположенным по адресу: ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/solution

6. Запустите веб-интерфейс агента.

В ADK встроен интерфейс тестирования под названием adk web . Он запускает облегченный чат, позволяющий немедленно связаться с агентом.

  1. Если GeminiCLI все еще открыт, нажмите control+C чтобы закрыть его. Теперь в терминале (он находится в папке solution , вы можете перейти в starter , чтобы протестировать свой код, запустив команду uv run adk web в папке starter ) выполните: 
    cd ~/holiday_workshop/02-Vibe-Coding-ADK-Agent/02-solution
uv run adk web --port 8000
  2. Cloud Shell сообщит вам, что на порту 8000 запущена служба. Нажмите «Предварительный просмотр в веб-браузере» -> «Предварительный просмотр на порту 8000» .

Проверьте агента

Теперь вы должны увидеть интерфейс чата. Давайте посмотрим, следует ли наш агент новым инструкциям и правильно ли он получает доступ к инструментам MCP.

Попробуйте выполнить следующие действия:

  • "Привет! Кто ты?"
    • (Ожидайте праздничного и восторженного отклика).
  • «Мне нужен фон для моей поздравительной открытки. Пусть это будет заснеженная деревня».
    • (Агент должен вызвать generate_holiday_scene . Обратите внимание, как она автоматически применяет стиль "милый/мультяшный", определенный в системных инструкциях).
  • «Создайте узор для свитера с маленькими кусочками пиццы».
    • (Агент должен вызвать generate_sweater_pattern ).

Сгенерированное изображение можно посмотреть здесь:

После завершения тестирования нажмите Control+C для выхода.

Заключение и дальнейшие шаги

Вы успешно создали агент Google ADK с использованием контекстно-зависимого подхода, применив технологию "Vibe-Coded"!

  • Мы определили контекст: мы использовали /memory add для определения экспертного профиля.
  • Мы строили итеративно: сначала создали каркас, а затем добавили соединения между инструментами.

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

7. Подключение ADK к пользовательскому интерфейсу

backend_architecture

Теперь, когда у нас есть определение агента, нам нужно его запустить. Именно здесь на помощь приходят Runner и Session Service .

Выполнение

  1. 👉 Введите следующую команду:
    cloudshell edit ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py
    Это откроет файл ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py в вашем редакторе.
  2. Замените # TODO: Create Session Service следующим содержимым: 
    from google.adk.sessions import InMemorySessionService
from google.adk.memory import InMemoryMemoryService
session_service = InMemorySessionService()
memory_service = InMemoryMemoryService()
  3. Замените # TODO: Initialize Runner следующим содержимым: 
    runner = Runner(
    app_name="agents",
    agent=christmas_agent,
    session_service=session_service,
    memory_service=memory_service,
)
  1. Просмотрите строку 158 в файле ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py ( никаких действий не требуется ): Если вам интересно, как приложение получает окончательный ответ? Ниже приведен цикл обработки событий, работающий на основе Runner: 
    async for event in runner.run_async(
    user_id=user_id,
    session_id=session_id,
    new_message=content
)

Углубленный анализ: архитектура и развертывание

Для обслуживания этого агента мы используем FastAPI .

  • Почему FastAPI? : Агенты часто испытывают проблемы с вводом-выводом (ожидание LLM). Асинхронная природа FastAPI идеально справляется с этим.
  • Отсутствие состояния : Обратите внимание, что наш API-интерфейс не сохраняет состояние . Мы не сохраняем переменные в глобальной области видимости. Мы полагаемся на session_id и SessionService для восстановления состояния для каждого отдельного запроса. Это означает, что вы можете развернуть его в Cloud Run (бессерверная архитектура) и масштабировать до нуля!

8. Попробуйте приложение с помощью Agent Magic.

  1. 👉💻 Введите в командную строку следующее:
    cd ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter
./start_app.sh
    Это откроет файл ~/holiday_workshop/03-Connect-ADK-MCP-UI/01-starter/backend/main.py в вашем редакторе.
  2. Результат будет выглядеть примерно так, как показано ниже: результат порта 👉👉 Убедитесь, что вы перешли по адресу http://localhost:5173/ или открыли новое окно и ввели http://localhost:5173/ .
  3. Затем вы увидите веб-сайт с интерфейсом чата: веб-сайт
  4. Для проверки загрузите одно изображение (это может быть вы или ваш питомец). загрузить
  5. 👉 Затем спросите
    Can you generate a picture my cat wearing snowflake pattern sweater?
    Сгенерированное изображение вы увидите здесь: кот
  6. 👉💻 После завершения тестирования нажмите control+C в терминале, чтобы завершить процесс.

Если что-то работает не так, как ожидалось, вы можете перейти в папку ~/holiday_workshop/03-Connect-ADK-MCP-UI/02-solution , запустить ./start_app.sh , а затем выполнить те же действия, что и выше.

9. Банк памяти Vertex AI

агент_память

Кратковременная и долговременная память

  • Кратковременный контекст : "Что я только что сказал?" (История сеанса). Эта информация теряется при закрытии окна чата.
  • Долговременная память : «Какой мой любимый язык программирования?» (Пользовательские предпочтения). Эта информация должна сохраняться навсегда.

Vertex AI Memory Bank обеспечивает долговременное хранение данных. Он позволяет агенту хранить и извлекать персонализированную информацию о пользователе.

Сессии против банка памяти

  • Сессии ( VertexAiSessionService ): Это журнал . В нем хранится необработанная хронологическая последовательность каждого сообщения, вызова инструмента и события ( AppendEvent , ListEvents ). Он предоставляет достоверную информацию о произошедшем .
  • Банк памяти ( VertexAiMemoryBankService ): это хранилище знаний . Он хранит синтезированные, долговременные факты ( GenerateMemories , RetrieveMemories ). Он привязан к конкретному user_id , обеспечивая конфиденциальность и изоляцию.
  1. 👉💻 Введите в командную строку следующее:
    cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py
    Это откроет файл ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/main.py в вашем редакторе.
  2. Найдите # TODO: Create Vertex AI Session Service & Memory Bank Service , замените всю строку следующим содержимым: 
        session_service = VertexAiSessionService(
        project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
    )
    memory_service = VertexAiMemoryBankService(
        project=PROJECT_ID, location=LOCATION, agent_engine_id=AGENT_ENGINE_ID
    )

memory_compare

  1. 👉💻 Введите в командную строку следующее:
    cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py
    Это откроет файл ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py в вашем редакторе.
  2. Замените # TODO: Set Up Configuration следующим текстом: 
    # Basic configuration types
MemoryBankConfig = types.ReasoningEngineContextSpecMemoryBankConfig
SimilaritySearchConfig = (
    types.ReasoningEngineContextSpecMemoryBankConfigSimilaritySearchConfig
)
GenerationConfig = types.ReasoningEngineContextSpecMemoryBankConfigGenerationConfig

# Advanced configuration types
CustomizationConfig = types.MemoryBankCustomizationConfig
MemoryTopic = types.MemoryBankCustomizationConfigMemoryTopic
CustomMemoryTopic = types.MemoryBankCustomizationConfigMemoryTopicCustomMemoryTopic
GenerateMemoriesExample = types.MemoryBankCustomizationConfigGenerateMemoriesExample
ConversationSource = (
    types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSource
)
ConversationSourceEvent = (
    types.MemoryBankCustomizationConfigGenerateMemoriesExampleConversationSourceEvent
)
ExampleGeneratedMemory = (
    types.MemoryBankCustomizationConfigGenerateMemoriesExampleGeneratedMemory
)

процесс памяти

  1. 👉 В том же файле: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py . Найдите строку # TODO: Set up topic и замените её на следующую: 
        custom_topics = [
        # Topic 1: Sweater Preference
        MemoryTopic(
            custom_memory_topic=CustomMemoryTopic(
                label="sweater_preference",
                description="""Extract the user's preferences for sweater styles, patterns, and designs. Include:
                - Specific patterns (snowflake, reindeer, geometric, fair isle, solid, etc.)
                - Style preferences (chunky knit, cardigan, pullover, turtleneck, oversized, fitted)
                - Color preferences (red, green, navy, pastel, etc.)
                - Material preferences if mentioned (wool, cotton, cashmere, itchy/soft)
                - Themes (retro, modern, ugly christmas sweater, elegant)

                Example: "User wants a retro style sweater with a pixelated reindeer pattern."
                Example: "User prefers dark blue colors and hates itchy wool."
                """,
            )
        ),
        # Topic 2: Personal Context
        MemoryTopic(
            custom_memory_topic=CustomMemoryTopic(
                label="personal_context",
                description="""Extract the user's personal context including hobbies, pets, interests, job, and preferred scenes. Include:
                - Hobbies and activities (skiing, reading, gaming, cooking, etc.)
                - Pets (type, breed, name, color)
                - Job or profession if relevant to their style
                - General interests (sci-fi, nature, vintage, tech)
                - Preferred scenes or vibes (cozy fireplace, snowy mountain, cyberpunk city, beach)

                Example: "User has a golden retriever named Max."
                Example: "User loves skiing and wants a snowy mountain background."
                Example: "User is a software engineer who likes cyberpunk aesthetics."
                """,
            )
        )
    ]
  2. 👉 В том же файле: 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py . Найдите строку # TODO: Create Agent Engine и замените её на следующую: 
        agent_engine = client.agent_engines.create(
        config={
            "display_name": AGENT_DISPLAY_NAME,
            "context_spec": {
                "memory_bank_config": {
                    "generation_config": {
                        "model": f"projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/gemini-2.5-flash"
                    },
                    "customization_configs": [customization_config]
                }
            },
        }
    )

Почему бы просто не воспользоваться подсказкой?

Вы можете спросить: «Почему бы нам просто не вставить историю действий пользователя в подсказку?»

  • Ограничения по размеру : контекстные окна большие, но не бесконечные. Вы не сможете вместить историю за 5 лет.
  • Стоимость : Обработка 1 миллиона токенов для каждого "Привет" обходится непомерно дорого.
  • Focus : Memory Bank выступает в роли поисковой системы для вашего агента. Она извлекает только релевантную информацию.
  1. 👉💻 Введите в командную строку следующее:
    cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py
    Это откроет файл ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py в вашем редакторе.
  2. В файле ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py замените # TODO: Add PreloadMemoryTool следующим текстом: 
    if USE_MEMORY_BANK:
    agent_tools.append(PreloadMemoryTool())

PreloadMemoryTool & add_session_to_memory

В файле agent.py вы увидите два ключевых компонента:

  • PreloadMemoryTool : Это инструмент, который позволяет агенту «погуглить» самого себя. Если пользователь задает расплывчатый вопрос, например: «Принесите мне мой обычный кофе», агент может использовать этот инструмент, чтобы запросить у банка памяти информацию о «кофейных предпочтениях» перед ответом.
  • add_session_to_memory : Это фоновый коллбэк.
    • Почему асинхронный режим? Экономия памяти занимает время (подведение итогов чата, извлечение фактов). Мы не хотим, чтобы пользователь ждал этого. Мы запускаем это в фоновом режиме ( add_session_to_memory ) с помощью after_agent_callback .

10. Банк памяти в действии

  1. 👉💻 Введите в командную строку следующее:
    cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
./use_memory_bank.sh
    Результат вы увидите ниже: deploy_agent_result Проверьте файл ~/holiday_workshop/.env , вы увидите ( никаких действий не требуется ) 
    USE_MEMORY_BANK=TRUE
AGENT_ENGINE_ID={agent_engine_id}
  2. 👉💻 Проверьте использование памяти с помощью пользовательского интерфейса приложения. Введите в командной строке следующее:
    cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
./start_app.sh
    Убедитесь, что вы перешли по адресу http://localhost:5173/ или открыли новое окно и ввели http://localhost:5173/ . Обратите внимание, что Uvicorn running on http://0.0.0.0:8000 — это всего лишь серверная часть, а не та ссылка, по которой мы хотим перейти. Теперь интерфейс чата на веб-сайте стал вашим персональным агентом! веб-сайт
  3. 👉Проверьте память. Если вы введете в интерфейсе: 
    I want a sweater that matches my dog. He's a golden retriever.

    I'm a programmer, so I want something geeky. Maybe a matrix style?

    I like snowflake sweater pattern

Агент идентифицирует это как предпочтение и сохранит его в Банке памяти.

На следующей неделе (или в любое время, когда вы перезапустите приложение с помощью Control+C и ./start_app.sh ), если вы спросите: 

what is my preference on sweater pattern?

Агент запросит данные из Банка памяти , увидит ваши предпочтения и сгенерирует выкройку свитера без вашего запроса. 10-результат

  1. Проверьте в Vertex AI Agent Engine, перейдя в консоль Google Cloud Agent Engine.
    • Убедитесь, что вы выбрали проект в верхнем левом углу в выпадающем списке проектов: селектор проектов
    • И проверьте агентский движок, который вы только что развернули с помощью предыдущей команды use_memory_bank.sh агентский движок Перейдите в созданный вами агентский движок.
  2. В этом развернутом агенте перейдите на вкладку Memories , здесь вы можете просмотреть всю память. просмотр памяти

Поздравляем! Вы только что подключили банк памяти к своему агенту!

11. Заключение

Краткое содержание

Вы успешно разработали и создали полноценную агентную систему.

  • Подключение : Вы использовали MCP для стандартизации способа доступа вашего агента к локальным инструментам.
  • Оркестрация : Вы использовали ADK для управления сложным циклом логических рассуждений, необходимым для многоэтапных задач.
  • Персонализация : Вы использовали Memory Bank для создания постоянного обучающего слоя, запоминающего контекст пользователя.

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

  • Создайте собственный MCP-сервер : разработайте сервер для вашего внутреннего API или базы данных.
  • Изучите шаблоны ADK : ознакомьтесь с «циклами рассуждений» и «оркестрацией» в документации ADK.
  • Развертывание : Перенесите свой агент с локального скрипта в производственный сервис на платформе Cloud Run.