YouTube Search Assistant with ADK, MCP and Gemma 3

使用 ADK、MCP 和 Gemma 3 构建 YouTube 搜索助手

这是一个实用示例，演示如何通过 Google 的 Agent Development Kit（ADK）、模型上下文协议（MCP）以及借助 Ollama 运行的 Gemma 3 模型，实现 YouTube 搜索功能。

📚 目录

• 🔍 简介
• 🏗️ 架构
  • 🧩 核心组件
  • 📊 架构图
  • 🔄 数据流
  • ✨ 技术亮点
• 🚀 功能
• 🧠 核心概念
  • ADK - Agent Development Kit
  • MCP - Model Context Protocol
  • ADK 中的 Agent
  • 使用 MCP 的工具
  • Ollama 集成
• 📋 要求
• 🚦 开始使用
  • 1. 安装步骤
  • 2. 设置
  • 3. 使用方法
• 🔄 工作原理
• 📁 项目结构
• ⚠️ 故障排除
• 📦 仓库
• 👨‍💻 作者
• 📄 许可证

🔍 简介

本项目展示了如何利用 Google 的 ADK（Agent Development Kit）和 MCP（Model Context Protocol），构建一个由 Google 最新大模型 Gemma 3 驱动的 Agent。项目演示了如何：

• 通过 Ollama 连接本地运行的 Gemma 3
• 使用 MCP 实现 YouTube 搜索功能
• 创建一个能够整理并呈现搜索结果的对话式 Agent

🏗️ 架构

🧩 核心组件

• Google ADK - 提供 Agent 框架
• 模型上下文协议（MCP） - 规范工具通信
• Gemma 3（12B） - 驱动语言理解与生成
• Ollama - 在本地托管 Gemma 模型
• MCP YouTube Search - 提供 YouTube 搜索功能
• Python 3.9+ - 基础运行环境

📊 架构图

🔄 数据流

1. 用户通过界面提交查询
2. ADK Agent Framework 处理查询并判断意图
3. 如果需要搜索 YouTube：
   • 请求会被路由到 MCP 工具注册表
   • MCP YouTube Search 工具接收查询
   • 调用 SERP API 获取 YouTube 搜索结果
   • 通过 MCP 标准化格式返回结果
4. Gemma 3 模型（通过 Ollama 和 LiteLlm）：
   • 接收搜索结果
   • 生成自然语言回复
   • 将搜索结果整理为易读的项目符号列表
5. 将整理后的回复返回给用户界面

✨ 技术亮点

• Google ADK
  管理对话流程和工具编排。
• 模型上下文协议（MCP）
  实现模型与工具之间的标准化通信。
• 通过 Ollama 使用 Gemma 3
  提供高质量文本生成和工具调用能力。
• LiteLlm 集成
  将 ADK 无缝连接到由 Ollama 托管的模型。
• SERP API
  通过搜索 API 提供 YouTube 数据访问能力。

🚀 功能

• 🔍 使用自然语言查询搜索 YouTube 视频
• 🤖 由运行在 Ollama 上的 Gemma 3 驱动
• 📋 以清晰易读的格式整理搜索结果
• 🛠️ 基于 Google 的 Agent Development Kit（ADK）构建
• 🔄 集成 MCP（Model Context Protocol），实现无缝工具通信

🧠 核心概念

ADK - Agent Development Kit

Agent Development Kit（ADK） 是一个开源、以代码为先的 Python 工具包，用于构建智能 AI Agent。

MCP - Model Context Protocol

Model Context Protocol（MCP） 是模型与工具之间的通信标准。它支持：

• 统一的工具调用模式
• 结构化数据交换
• 工具组合与串联
• 与语言无关的工具定义

ADK 中的 Agent

ADK 中的 Agent 负责协调 AI 交互。在本项目中，我们使用 LlmAgent。它是 ADK 的核心组件，充当应用程序中负责“思考”的部分，并且能够：

• 利用大语言模型（LLM）进行推理和理解
• 管理对话历史和上下文
• 根据用户查询协调工具的使用

使用 MCP 的工具

本项目中的工具使用 MCP（Model Context Protocol） 框架实现，该框架：

• 定义了工具交互的标准接口
• 让大模型能够轻松发现工具
• 规范输入／输出格式
• 便于组合工具

MCP YouTube 搜索工具提供了一种标准化方式，让 Agent 能够使用 YouTube 搜索功能。

Ollama 集成

Ollama 提供了在本地运行 Gemma 3 和其他大语言模型的方式。Google ADK 通过以下方式连接到 Ollama：

• LiteLlm - 用于规范与不同大模型提供商通信的封装器
• 用于优化模型性能的自定义配置

📋 要求

• Python 3.9+
• 已安装 Ollama，并安装 Gemma 3 模型
• 用于 YouTube 搜索的 SERP API 密钥

🚦 开始使用

1. 安装步骤

克隆此仓库：

git clone https://github.com/arjunprabhulal/adk-mcp-gemma3.git
cd adk-mcp-gemma3

2. 设置

创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

安装依赖项：

pip install -r requirements.txt

设置 SERP API 密钥：

在根目录中创建一个 .env 文件，并填入 SERP API 密钥：

SERP_API_KEY=your_serp_api_key_here

拉取 Gemma 3 模型：

ollama pull gemma3:12b

3. 使用方法

选项 1：基于 Web 的 UI（推荐用于调试）

使用 ADK 的基于浏览器的开发者 UI 运行 Agent：

# Navigate to the parent directory
cd adk-mcp-gemma3

# Start the web interface
adk web

你应该会看到类似以下的输出：

然后在浏览器中打开提供的 URL（通常为 http://localhost:8000）。

• 从左上角的下拉菜单中选择“search”
• 在聊天界面中输入查询
• 你可以检查工具调用和模型回复，并查看详细的执行流程

选项 2：命令行

直接运行 Agent：

python -m search

现在，你可以通过让 Agent 查找 YouTube 视频来与它交互。

查询示例：

• “查找关于 Google Cloud Next 25 的视频”
• “搜索 Python 编程教程的 YouTube 视频”
• “查找关于机器学习入门的视频”

🔄 工作原理

实现过程分为以下步骤：

1. Agent 初始化：

   • 创建一个 LlmAgent，并引用托管在 Ollama 上的 Gemma 3 模型
   • 使用合适的指令配置 Agent
   • 将 YouTube 搜索工具添加到 Agent 的功能中

2. 工具定义：

   • 通过 MCP 定义 YouTube 搜索函数
   • MCP 为模型与工具交互提供标准化方式
   • 工具连接到 SERP API，以实现 YouTube 搜索功能

3. 查询处理：

   • 将用户查询传递给 Agent
   • Gemma 3 根据查询决定是否使用 YouTube 搜索工具
   • 如有需要，模型会生成合适的搜索查询
   • 模型会处理并格式化结果

4. 生成回复：

   • Agent 处理所有信息并格式化搜索结果
   • 将输出作为清晰的项目符号列表返回给用户
   • 每条结果都包含标题、链接、频道、描述和元数据

📁 项目结构

adk_mcp_gemma3/
├── Images/
│   ├── adk-gemma3.gif           # Demo gif of the application
│   └── adk-gemma-web.gif        # Web interface demo
├── search/
│   ├── __init__.py              # Package initialization
│   └── agent.py                 # Agent implementation with ADK
├── .gitignore                   # Git ignore file
├── README.md                    # Project documentation
├── LICENSE                      # MIT license
└── requirements.txt             # Dependencies

⚠️ 故障排查

1. 模型加载问题：

   • 确保 Ollama 正在运行：ollama list 应显示 gemma3:12b 模型。
   • 如果模型加载失败，请再次尝试：ollama pull gemma3:12b。

2. API 密钥问题：

   • 确认 SERP API 密钥已在 .env 文件中正确设置。
   • 单独测试 API 密钥，确保其有效。

3. 内存限制：

   • 12B 模型需要大量 RAM/VRAM。
   • 如果遇到内存问题，可考虑使用更小的模型，例如 gemma3:7b。

4. 函数调用问题：

   • 如果模型未能正确使用工具，请尝试让工具描述更加明确。
   • 确保查询明确需要外部信息。

5. LiteLLM/Ollama KeyError 错误：

   • Ollama 的 JSON 格式响应与 LiteLLM 的解析之间存在一个已知问题，可能导致 KeyError: 'name' 错误。
   • 当 Ollama 返回的 JSON 格式并非专门用于工具调用时，就会出现此问题。
   • 错误示例如下：KeyError: 'name'，出现在 litellm/llms/ollama/completion/transformation.py
   • 已在 LiteLLM 软件包的 PR #9966 中提交修复，但仍在等待审核和合并。
   • 使用 Ollama 模型进行函数调用时，此错误可能导致应用崩溃或陷入无限循环。
   • 临时解决方法：
     • 根据 PR #9966 中的更改，手动修补本地 LiteLLM 安装
     • 尽可能避免在 Ollama 请求中使用 format=json
     • 等待 PR 合并，并更新到包含此修复的下一个 LiteLLM 版本

📦 仓库

此项目可在 GitHub 上获取：arjunprabhulal/adk-mcp-gemma3。

如需了解另一个使用 ADK 进行函数调用的相关项目，请查看 arjunprabhulal/adk-gemma3-function-calling。

👨‍💻 作者

由 Arjun Prabhulal 创建。有关 AI/ML 和生成式 AI 的更多文章，请关注 Medium 上的 Arjun Prabhulal。

📄 许可证

本项目采用免费且开放的许可证发布。任何人都可以出于任何目的（包括商业应用）自由使用、修改、分发或基于此代码进行开发，不受限制。