使用 ADK、MCP 和记忆库构建个性化智能体

1. 简介

现代代理技术栈

构建生产级 AI 智能体需要的远不止大语言模型 (LLM)。虽然 LLM 提供了推理能力，但强大的代理还需要与外部世界互动、管理对话状态，并记住用户随时间变化而产生的偏好。

在此研讨会中，您将学习如何使用以下三项基础技术来设计和构建全面的智能体系统：

1. 连接性 (MCP)：让智能体能够访问本地工具和数据。
2. 编排 (ADK)：用于管理代理的推理循环和状态。
3. 记忆（记忆库）：提供长期个性化上下文。

核心概念

组件	函数
Model Context Protocol (MCP)	一种通用标准，可将 AI 模型连接到外部系统（数据库、文件系统、API），而无需自定义集成。
智能体开发套件 (ADK)	一个框架，可为代理提供运行时环境，管理事件循环、状态转换和工具执行。
会话服务	处理短期记忆。它会保留即时对话上下文（例如，“用户刚才问了什么？”），但在会话结束时会清除。
Vertex AI Memory Bank	处理长期记忆。它会持久保存用户特定的事实和偏好设置（例如，“用户偏好 Python”）无限期存储，以便代理在未来的互动中提供个性化服务。
Vertex AI Agent Engine	一种托管式基础架构服务，可大规模托管代理逻辑和内存组件。

您将构建的内容

为了演示这些概念，您将构建一个节日设计助理。该代理将能够接收高级别用户请求，并自主编排本地 Python 工具来生成个性化代码和图片。

您将经历三个阶段：

1. 工具层：创建 MCP 服务器以向 AI 公开本地 Python 函数。
2. 智能体层：使用 ADK 构建可规划和执行多步骤工作流的智能体。
3. 记忆层：集成记忆库，使智能体能够学习并记住用户风格偏好。

2. 设置

为了让 AI 代理正常运行，我们需要两样东西：一个 Google Cloud 项目来提供基础。

第 1 部分：启用结算账号

• 您需要声明拥有 5 美元赠金的结算账号，以便进行部署。请务必使用您的 Gmail 账号。

无需提供信用卡或付款信息 - 您将获得 5 美元的免费积分。只需不到 2 分钟，您只需输入自己的姓名并接受积分即可。

第二部分：开放环境

1. 👉 点击此链接可直接前往 Cloud Shell Editor
2. 👉 如果系统在今天任何时间提示您进行授权，请点击授权继续。
3. 👉 如果终端未显示在屏幕底部，请打开它：
   • 点击查看
   • 点击终端
4. 👉💻 在终端中，使用以下命令验证您是否已通过身份验证，以及项目是否已设置为您的项目 ID：

   gcloud auth list
   

5. 👉💻 从 GitHub 克隆引导项目：

   git clone https://github.com/cuppibla/holiday_workshop
   

6. 👉💻 从项目目录运行设置脚本。

   cd ~/holiday_workshop
   ./init.sh
   

   ⚠️ 项目 ID 注意事项：脚本会建议一个随机生成的默认项目 ID。您可以按 Enter 键接受此默认值。

   不过，如果您想创建特定的新项目，可以在脚本提示时输入所需的项目 ID。

   脚本会自动处理其余设置流程。
7. 👉💻 设置所需的项目 ID：

   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 增强功能

AI 的“USB-C”时刻

想象一下，如果您每次购买新鼠标，都必须将其焊接到主板上。这是 AI 工具在不久之前的状态。开发者必须编写自定义“粘合代码”才能将 LLM 连接到数据库、文件系统或 API。

输入 Model Context Protocol (MCP)。您可以将 MCP 视为 AI 应用的 USB-C 端口。它提供了一种将 AI 模型连接到数据源和工具的标准化方式。

如果您为工具构建 MCP 服务器一次，就可以将其插入 Gemini CLI、IDE 或任何其他符合 MCP 标准的客户端，而无需更改任何代码。

您将构建的内容

在此 Codelab 中，您将构建一个节日设计助理，该助理可以：

1. 使用 MCP 连接到本地环境（工作室工具）。
2. 使用智能体开发套件 (ADK) 可靠地管理对话上下文。
3. 记住您的偏好设置（例如，“我更喜欢 Python 代码”）在不同会话中使用 Vertex AI 记忆库。

警告：请确保您已对 Google Cloud CLI (gcloud auth login) 进行身份验证，然后再运行代码示例。

构建服务器逻辑

我们已准备好环境，但服务器逻辑不完整。我们需要实现我们的代理最终将用于制作节日贺卡的四种特定工具。

第 1 部分：打开服务器框架

我们将在 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 客户端）已完成。不过，这四个核心函数目前是空的占位符。

第二部分：实现节日场景生成器

首先，我们需要一个工具，该工具可以获取用户的兴趣（例如，“鸟类”）并将其转换为丰富而详细的提示，以便优化图片生成效果。

找到 generate_holiday_scene 函数内的注释 #REPLACE_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"

第 3 部分：实现最终照片效果

最后，我们希望确保光线和风格看起来写实且喜庆。

找到注释 #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

您会看到 fastmcp>=2.13.3 这一新依赖项已添加到 ~/holiday_workshop/01-MCP-Files-Testing/01-starter/pyproject.toml 文件中。

4. 使用 Gemini CLI 测试 MCP 服务器

现在，我们的服务器代码已完成，如何对其进行测试？

通常，测试后端服务器需要构建前端界面或编写复杂的 curl 请求。不过，在这里我们可以使用 Gemini CLI。

什么是 Gemini CLI？

Gemini CLI 是一种命令行工具，可让您直接在终端中与 Gemini 模型对话，但它具有一项超能力：可以自动发现并使用在本地 MCP 服务器上运行的工具。

这对于开发非常有用，因为它可以隔离逻辑。在您担心构建 Web 界面或代理框架之前，可以先验证模型是否了解您的工具并能正确调用它们。

连接并运行

我们将使用 mcp add 命令告知 Gemini CLI 管理我们的服务器。

在终端中，运行以下命令：

gemini mcp add holidays uv run ~/holiday_workshop/01-MCP-Files-Testing/01-starter/mcp_server.py

• add holidays：我们为服务器起了个昵称（“holidays”）。
• uv run ...：我们提供了明确的命令来启动刚刚修改的 Python 服务器。

让我们一起创造奇迹！

现在，启动聊天会话：

gemini

尝试以下提示，测试 Gemini 是否可以“看到”您的新工具。请注意，您可能需要允许 Gemini CLI 使用我们的节假日工具。

• 👉 用户：

  "I want to create a festive holiday photo. I like birds a lot."
  

• Gemini：

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

• Gemini：

  *Thinking...*
  *Calling tool: generate_sweater_pattern(motif='reindeer')*
  
  Done! Saved at generated_pattern.png
  

  由于您使用了 MCP，AI 准确地了解了要调用哪个 Python 函数来满足您的请求！

查看图片

• 按 Control+C 结束 Gemini CLI。
• 检查文件夹 ~/holiday_workshop/01-MCP-Files-Testing/01-starter/static 中的生成图片。

在此处查看您的照片：

总结与后续步骤

恭喜！您已成功构建可正常运行的 MCP 服务器。现在，您拥有了一套实用的“AI 工具”，可以生成图案、合成图片和优化场景。

不过，您是否注意到上述测试中的某些内容？您必须主导整个流程。您必须先要求生成场景，然后要求生成图案，然后要求将它们组合起来。

虽然 Gemini 很智能，但对于复杂的生产工作流程（我们需要先生成图案，然后才能将其放在毛衣上，并在图片生成失败时处理错误），我们希望有更多控制权。我们希望有一个专用系统，可以规划、评价自己的工作，并管理我们的节日贺卡的状态，而无需我们每一步都指导它。

在下一部分中，我们将整理这种创意混乱。我们将实现智能体开发套件 (ADK)，以构建一个结构化智能体，将这些 MCP 工具编排到完美的生产流水线中。

5. 以氛围编程方式打造 ADK 智能体

我们有一套可用的工具（我们的 MCP 服务器），但目前，我们是所有繁重工作的承担者，需要准确地告知 Gemini 要调用哪个工具以及何时调用。

在本部分中，我们将构建一个 AI 智能体：一个可以自主推理、规划和执行多步任务的系统。为此，我们将使用智能体开发套件 (ADK)。

什么是代理？

如果将 MCP 工具比作“手”（负责执行工作），那么 Agent 就是“大脑”。智能体使用 LLM 来理解用户意图（“帮我制作一张节日贺卡”），将其分解为多个步骤（“首先，我需要一个场景，然后是一个图案…”），并决定使用哪些工具来实现目标。

什么是 ADK？

智能体开发套件 (ADK) 是 Google 提供的一个框架，可让您轻松构建这些智能体。它会处理复杂的“管道”问题，例如管理对话记录、连接到工具以及在不同模型之间切换，因此您可以专注于应用的个性和逻辑。

基于上下文的氛围编程

使用单个大型提示生成代码是一种常见模式。不过，在构建复杂的应用时，最好将 AI 视为可随时间推移保持上下文的合作伙伴。

在编写任何代码之前，我们将使用 Gemini CLI 的记忆功能来做好准备。

1. 准备环境

打开终端并导航到初始目录：

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

启动 Gemini CLI：

gemini

2. 管理上下文和记忆

在进行氛围编码时，AI 需要知道自己是谁以及自己知道什么。Gemini CLI 允许我们明确管理这一点。

• /memory show：输入此内容可查看 AI 目前对您的项目和会话的了解程度。
• /memory add：使用此参数注入 AI 在整个对话过程中应记住的基础知识。

我们先来定义一下编码伙伴的角色。在 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 CLI 中输入以下提示：

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 CLI 中输入以下提示：

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. 运行代理 Web 界面

ADK 附带一个名为 adk web 的内置测试接口。这样会启动一个轻量级聊天界面，以便我们立即与代理对话。

1. 如果您仍打开着 GeminiCLI，请按 control+C 将其关闭。现在，在终端中（位于 solution 文件夹中，您可以前往 starter 文件夹，通过在 starter 文件夹中运行 uv run adk web 来测试代码），运行以下命令：

   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 定义了专家角色。
• 我们以迭代方式构建了 Iteratively：我们先创建了框架，然后添加了工具连接。

内置的 ADK 网络预览功能非常适合测试，但对于最终产品，我们希望获得自定义的品牌体验。在下一部分中，我们将此代理集成到自定义 Web 前端中。

如果您在研讨会期间遇到 Unexpected response from metadata server: service account info is missing 'email' field，则意味着您需要刷新 Cloud Shell 并重新运行 gcloud config set project $(cat ~/project_id.txt) --quiet 以设置 project id，然后才能继续

7. 将 ADK 与界面相关联

现在我们已经有了代理定义，接下来需要运行它。这时，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()
   

   会话服务是智能体的“工作记忆”。

   • 角色：它存储当前对话的杂乱无章的即时历史记录（例如，“我刚才问了什么？”）。
   • 两种变种：
   • InMemorySessionService：快速、简单，但健忘。如果您重启服务器，代理会忘记所有内容。非常适合测试。
   • VertexAiSessionService：稳健、由数据库提供支持。它会将状态保存到 Google Cloud，因此对话可以在数周后或在服务器重启后继续进行。
3. 将 # TODO: Initialize Runner 替换为以下内容：

   runner = Runner(
       app_name="agents",
       agent=christmas_agent,
       session_service=session_service,
       memory_service=memory_service,
   )
   

Runner：如果说代理是“大脑”，那么 Runner 就是“心脏”。让血液循环起来。Runner 负责：

• 将代理绑定到用户和会话。
• 执行事件循环。
• 管理状态转换。

4. 查看第 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
   )
   

事件循环 ADK 代理不仅仅是“回复”。他们会循环思考。当您调用 runner.run_async() 时：

1. 用户输入进入循环。
2. 规划：智能体考虑其工具和目标。
3. 行动：如果合适，它会调用工具（例如 list_files）。
4. 观察：读取工具输出。
5. 反思：决定是否需要更多信息，或者是否可以回答。
6. 循环：重复执行第 2-5 步，直到满足条件。
7. 回答：向用户提供最终答案。

深入分析：架构和部署

我们使用 FastAPI 来提供此代理。

• 为什么选择 FastAPI？：代理通常受 I/O 限制（等待 LLM）。FastAPI 的异步特性可完美处理此问题。
• 无状态：请注意，我们的 API 端点是无状态的。我们不会将变量保存在全局范围内。我们依靠 session_id 和 SessionService 来重建每个请求的状态。这意味着您可以将其部署到 Cloud Run（无服务器），并扩缩到零！

8. 体验智能体带来的应用魔力

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/。

   请注意，它不是后端服务器的链接：Uvicorn running on http://0.0.0.0:8000

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 Memory Bank

短期记忆与长期记忆

• 短期情境：“我刚才说了什么？”（会话历史记录）。聊天窗口关闭后，这些信息会丢失。
• 长期记忆：“我最喜欢的编程语言是什么？”（用户偏好设置）。此值应永久保留。

Vertex AI 记忆库可提供这种长期存储。它允许代理存储和检索用户的个性化信息。

会话与记忆库

• 会话 (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
       )
   
   

3. 👉💻 在命令中输入以下内容：

   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。
4. 将 # 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
   )
   

核心功能

Vertex AI 记忆库不仅是一个数据库，还是一项主动认知服务。

• 记忆提取：系统使用 LLM 读取对话，并根据我们定义的 CustomMemoryTopic 架构（例如，“毛衣偏好”）。它会忽略闲聊内容并保存信号。
• 记忆整合：自动将新事实与旧事实合并。如果用户说“我喜欢红色”，但后来又说“实际上，我更喜欢蓝色”，记忆库会更新记忆记录，而不是创建冲突的重复记录。
• 异步生成：记忆在后台生成。当记忆库“思考”对话时，代理不会停滞不前。

5. 👉 在同一文件中：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."
                   """,
               )
           )
       ]
   

6. 👉 在同一文件中：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]
                   }
               },
           }
       )
   

Agent Engine

代理引擎是云端“大脑硬件”。它会管理：

• 向量数据库：用于存储记忆。
• 编制索引：使回忆可供搜索。
• API：允许代理查询该 API。运行 deploy_agent.py 时，您实际上是在预配此硬件。

为什么不直接使用提示？

您可能会问：“为什么我们不直接将用户的历史记录粘贴到提示中？”

• 大小限制：上下文窗口很大，但并非无限大。无法容纳 5 年的历史记录。
• 费用：每处理 100 万个“Hello”词元，费用都非常高昂。
• 重点：记忆库充当代理的搜索引擎。它只会检索相关事实。

7. 👉💻 在命令中输入以下内容：

   cloudshell edit ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py
   

   这会在编辑器中打开 ~/holiday_workshop/04-Adding-Memory-Bank/01-starter/backend/agent.py。
8. 在文件 ~/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：此工具可让代理“自行 Google 搜索”。如果用户提出的问题比较模糊，例如“给我来杯我常喝的咖啡”，代理可以在回答之前使用此工具向记忆库查询“咖啡偏好”。
• add_session_to_memory：这是一个后台回调。
  • 为什么要使用异步？保存记忆需要时间（总结对话、提取事实）。我们不希望用户等待此操作。我们使用 after_agent_callback 在后台 (add_session_to_memory) 运行它。

10. 记忆库的实际应用

1. 👉💻 在命令中输入以下内容：

   cd ~/holiday_workshop/04-Adding-Memory-Bank/01-starter
   ./use_memory_bank.sh
   

   您会看到如下结果：

   此 use_memory_bank.sh 脚本首先使用文件 04-Adding-Memory-Bank/01-starter/backend/deploy_agent.py 将代理引擎附加到您的代理，以便您的代理可以使用 Vertex AI 记忆库。然后，它会为您更新 .env 文件，以便将 Agent Engine ID 保存为 environmental variable。

   检查 ~/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?

智能体将查询记忆库，了解您的偏好，并在未收到要求的情况下生成毛衣图案。

个性化：这是打造实用智能体的关键。通过记住用户偏好（毛衣图案、个人情境），智能体随着时间的推移会变得更加高效实用。

4. 在 Vertex AI Agent Engine 中进行验证，方法是前往 Google Cloud 控制台 Agent Engine
   • 请确保您从左上角的项目选择器中选择了项目：
   • 验证您刚刚通过上一个命令部署的代理引擎 use_memory_bank.sh点击您刚刚创建的代理引擎。
5. 点击此已部署代理中的 Memories 标签页，即可在此处查看所有记忆。

恭喜！您刚刚将记忆库附加到代理！

11. 总结

摘要

您已成功设计并构建了一个完整的代理系统。

• 连接：您使用 MCP 来标准化智能体访问本地工具的方式。
• 编排：您使用 ADK 来管理多步骤任务所需的复杂推理循环。
• 个性化：您使用记忆库创建了一个持久的学习层，用于记住用户上下文。

后续步骤

• 构建您自己的 MCP 服务器：为您的内部 API 或数据库创建服务器。
• 探索 ADK 模式：在 ADK 文档中了解“推理循环”和“编排”。
• 部署：将代理从本地脚本部署到 Cloud Run 上的生产服务。

继续构建：将 MCP（用于连接）与记忆库（用于个性化）相结合，可为下一代智能应用奠定基础。