具有记忆和 MCP 的 ADK Agentic 模式

1. 学习内容

欢迎参加 ADK 大师班 - 多智能体系统之旅

您即将踏入精彩纷呈的 AI 智能体世界。忘掉只能回答问题的简单聊天机器人吧。我们将深入研究 Agent Development Kit (ADK)，以构建能够推理、规划和使用工具来完成复杂任务的精密的自主系统。

翻唱版

学完本教程后，您将能够：

  • 构建您的第一个 AI 智能体：从零开始构建一个功能齐全的智能体，该智能体能够理解用户需求、使用 Google 搜索等工具，并生成详细且实用的回答。
  • 构建多智能体系统：了解“智能体即工具”模式，这是一种革命性的概念，其中智能体将任务委托给其他专业智能体，从而创建一个协同工作的 AI 专家团队。
  • 编排复杂的工作流：除了简单的委托之外，您还可以掌握路由器、顺序链、循环和并行执行等高级模式，从而构建强大、高效且智能的应用，以处理几乎所有请求。
  • 为智能体赋予记忆力：了解对话记忆的关键作用，让智能体能够处理后续问题、从反馈中学习，并顺畅地管理多步骤任务。
  • 与 MCP 连接：与 MCP Toolbox 连接。

现在就开始吧！🚀

2. 设置：获取 API 密钥

Google AI Studio API 密钥设置

所需条件：

  • Python 3.9 或更高版本（python3 --version 进行检查）
  • 一个 Google 账号（用于创建 AI Studio 密钥）
  • 终端 - 本地机器或 Cloud Shell 均可
  • 约 10 分钟

为了支持我们的 AI 代理，我们需要从 Google AI Studio 获取 Gemini API 密钥。这是最快的入门方式。

第 1 步 - 从 AI Studio 获取 Gemini API 密钥（1 分钟）

  1. 在新浏览器标签页中打开 https://aistudio.google.com/app/apikey。
  2. 使用您的 Google 账号登录。
  3. 点击右上角的“创建 API 密钥”。
  4. 系统会打开一个对话框，其中包含一个项目下拉菜单：
  • 如果您之前已创建 Google 项目：请选择该项目，然后点击在现有项目中创建 API 密钥
  • 如果不在列表中：点击“创建项目”。

aistudio

  1. 复制显示的 API 密钥。以 AIza... 开头，长度约为 40 个字符。

✏️ 将其粘贴到安全的位置 - 您将在下文第 4 步中用到它。

第 2 步 - 克隆代码库（1 分钟）

👉💻 打开终端（或 Cloud Shell），然后克隆教程代码库：

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

第 3 步 - 创建虚拟环境并安装依赖项

👉💻 创建并激活名为 .adk_env 的虚拟环境，然后安装依赖项：

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

您应该会在终端提示符的开头看到 (.adk_env)。

第 4 步 - 🔥 重要提示：添加您的 API 密钥

⚠️ 请勿跳过此步骤！在 adk_tutorial 文件夹的根目录中创建一个 .env 文件。此文件支持本 Codelab 中的每个会话 - ADK Web 会话（1-5）和命令行内存与 MCP 会话（6-7）都会自动读取该文件。

👉💻 使用您的密钥创建 .env 文件（将 your_actual_api_key_here 替换为第 1 步中的密钥）：

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

您的 ~/adk_tutorial/.env 现在应包含：

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 重要：将 your_actual_api_key_here 替换为第 1 步中的实际 API 密钥（以 AIza... 开头）。

✅ 检查点：您在 ~/adk_tutorial/.env 中有一个 .env 文件，其中包含您的 AIza... 密钥，并且终端提示显示 (.adk_env)。您已准备好构建智能体！

3. 第 1 次会话：在 ADK Web 中创建您的首个智能体

代理机器人正在阅读

通过运行以下命令打开 ADK Web：

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

运行命令后，您应该会在终端中看到表明 ADK Web 服务器已启动的输出，如下所示：

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 接下来，在浏览器中打开 http://localhost:8000，以访问 ADK 开发者界面。

webpreview

👉 召唤仪式已完成，代理现已运行。浏览器中的 ADK Dev UI 是您与 Familiar 的直接连接。

选择您的第一个代理：在界面顶部的下拉菜单中，选择 a_single_agent。

您可以点击此处选择 a_single_agent：单个代理的轨迹图片

您可以在此处查看轨迹：单个代理的轨迹图

👉 测试提示：

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. 会话 2：工作流智能体：顺序智能体、并行智能体、循环智能体

并行智能体

并行智能体

选择并行工作流代理：在界面顶部的下拉菜单中，选择 b2_parallel_agent。

👉 测试提示：

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

您可以点击此处选择 b2_parallel_agent：并行智能体的轨迹图

您可以在此处查看轨迹：并行智能体的轨迹图

顺序智能体

顺序智能体

选择顺序工作流代理：在界面顶部的下拉菜单中，选择 b1_sequential_agent。

👉 测试提示：

Find a good sushi near Standford and tell me how to get there.

您可以点击此处选择 b1_sequential_agent：顺序智能体的轨迹图

您可以在此处查看轨迹：sequential_agent 的跟踪图片

循环智能体

循环智能体

选择 Loop 工作流代理：在界面顶部的下拉菜单中，选择 b3_loop_agent。

👉 测试提示：

Plan a trip from Sunnyvale to San Francisco today.

您可以点击此处选择 b3_loop_agent：循环智能体的跟踪图片

您可以在此处查看轨迹：循环智能体的轨迹图片

5. 第 3 次会议：自定义代理

打开 ADK 网页界面后，从下拉菜单中选择 c_custom_agent。

👉 测试提示：

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

您可以点击此处选择 c_custom_agent：Custom_Agent 的跟踪图片

您可以在此处查看轨迹：Custom_Agent 的跟踪图片

6. 会话 4：编排器模式 - 路由代理

路由器代理

打开 ADK 网页界面后，从下拉菜单中选择 d_routing_agent。

👉 测试提示：

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

您可以点击此处选择 d_routing_agent：路由代理的跟踪图片

您可以在此处查看轨迹：路由代理的跟踪图片

7. 第 5 次会话：智能体即工具

打开 ADK 网页界面后，从下拉菜单中选择 e_agent_as_tool。

👉 测试提示：

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

您可以点击此处选择 e_agent_as_tool：将代理作为工具的追踪图片

您可以在此处查看轨迹：路由代理的跟踪图片

8. 第 6 次会议：具有长期记忆的代理

👉💻 前往文件夹并使用运行程序为智能体供电，测试长期记忆：

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 测试提示：

I like Art and Italian food.

然后按 Ctrl+C 结束会话。重新开始会话：

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 测试提示：

Plan a trip to San Francisco based on my preference.

9. 第 7 次会话：使用 MCP 为智能体赋能

第 1 步：准备本地数据库

👉💻 从代码库根目录创建示例数据库：

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

这会在 ~/adk_tutorial/ 中创建 destinations.db。

第 2 步：安装并运行 MCP Toolbox 服务器

👉💻 下载适用于您的操作系统的 MCP Toolbox 二进制文件：

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

下载完成后，运行

chmod +x toolbox

第 3 步

在一个终端中运行以下命令（让其保持运行状态 - 代理会在 http://127.0.0.1:7001 连接到该命令）：

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

在另一个终端中运行以下命令

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 测试提示（使用示例数据库中存在的城市 - 巴黎、罗马、纽约或东京）：

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?