YouTube Search Assistant with ADK, MCP and Gemma 3

ADK、MCP、Gemma 3 による YouTube 検索アシスタント

Google の Agent Development Kit（ADK）、Model Context Protocol（MCP）、および Ollama 経由の Gemma 3 モデルを使用して YouTube 検索機能を実装した実践的な例です。

📚 目次

• 🔍 はじめに
• 🏗️ アーキテクチャ
  • 🧩 コアコンポーネント
  • 📊 アーキテクチャ図
  • 🔄 データフロー
  • ✨ 技術ハイライト
• 🚀 機能
• 🧠 コアコンセプト
  • ADK - Agent Development Kit
  • MCP - Model Context Protocol
  • ADK のエージェント
  • MCP のツール
  • Ollama 統合
• 📋 要件
• 🚦 はじめに
  • 1. インストール手順
  • 2. セットアップ
  • 3. 使い方
• 🔄 仕組み
• 📁 プロジェクト構成
• ⚠️ トラブルシューティング
• 📦 リポジトリ
• 👨‍💻 作者
• 📄 ライセンス

🔍 はじめに

このプロジェクトは、Google の ADK（Agent Development Kit）と MCP（Model Context Protocol）を活用して、Google の最新大規模言語モデルである Gemma 3 を搭載したエージェントを構築する方法を紹介します。以下を示します。

• Ollama 経由でローカルホストされた Gemma 3 に接続する
• MCP を使用して YouTube 検索機能を実装する
• 検索結果を整形して提示できる会話型エージェントを作成する

🏗️ アーキテクチャ

🧩 コアコンポーネント

• Google ADK - エージェントフレームワークを提供します
• Model Context Protocol（MCP） - ツール間通信を標準化します
• Gemma 3（12B） - 言語理解と生成を担います
• Ollama - Gemma モデルをローカルでホストします
• MCP YouTube Search - YouTube 検索機能を提供します
• Python 3.9+ - ベースの実行環境です

📊 アーキテクチャ図

🔄 データフロー

1. ユーザーがインターフェースを通じてクエリを送信します
2. ADK エージェントフレームワークがクエリを処理し、意図を判定します
3. YouTube 検索が必要な場合：
   • リクエストは MCP ツールレジストリにルーティングされます
   • MCP YouTube Search ツールがクエリを受け取ります
   • SERP API が呼び出され、YouTube の結果を取得します
   • 結果は MCP の標準化された形式で返されます
4. Gemma 3 モデル（Ollama と LiteLlm 経由）：
   • 検索結果を受け取ります
   • 自然言語の応答を生成します
   • 検索結果を読みやすい箇条書きに整形します
5. 整形された応答がユーザーインターフェースに返されます

✨ 技術ハイライト

• Google ADK
  会話の流れとツールのオーケストレーションを管理します。
• Model Context Protocol（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） は、インテリジェントな AI エージェントを構築するためのオープンソースのコードファーストな Python ツールキットです。

MCP - Model Context Protocol

Model Context Protocol (MCP) は、モデルとツール間の通信のための標準規格です。これにより、次のことが可能になります:

• 一貫したツール呼び出しパターン
• 構造化されたデータ交換
• ツールの組み合わせとチェーン
• 言語に依存しないツール定義

ADK におけるエージェント

ADK における エージェント は、AI とのやり取りのオーケストレーターとして機能します。このプロジェクトでは LlmAgent を使用しています。これは ADK のコアコンポーネントであり、アプリケーションの「思考」部分として次の役割を担います:

• 推論と理解のために大規模言語モデル（LLM）を活用します
• 会話履歴とコンテキストを管理します
• ユーザーのクエリに基づいてツールの使用を調整します

MCP を使用したツール

このプロジェクトのツールは、MCP（Model Context Protocol） フレームワークを使用して実装されており、次の特徴があります:

• ツール連携のための標準インターフェースを定義します
• ツールを LLM が容易に発見できるようにします
• 入力/出力形式を構造化します
• ツールの組み合わせを容易にします

MCP YouTube 検索ツールは、エージェントが YouTube 検索機能と連携するための標準化された方法を提供します。

Ollama の統合

Ollama は、Gemma 3 やその他の大規模言語モデルをローカルで実行する方法を提供します。Google ADK は、次の方法で Ollama に接続します:

• LiteLlm - さまざまな LLM プロバイダーとの通信を標準化するラッパー
• モデルのパフォーマンスを最適化するためのカスタム設定

📋 要件

• Python 3.9+
• Gemma 3 モデルをインストールした Ollama
• 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 キーを設定します:

ルートディレクトリに、SERP API キーを含む .env ファイルを作成します:

SERP_API_KEY=your_serp_api_key_here

Gemma 3 モデルをプルします:

ollama pull gemma3:12b

3. 使用方法

オプション 1: Web ベースの UI（デバッグに推奨）

ADK のブラウザベースの開発者 UI を使用してエージェントを実行します:

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

# Start the web interface
adk web

次のような出力が表示されるはずです:

次に、提供された URL（通常は http://localhost:8000）をブラウザで開きます。

• 左上隅のドロップダウンメニューから「search」を選択します
• チャットインターフェースにクエリを入力します
• ツール呼び出し、モデルの応答を確認し、詳細な実行フローを表示できます

オプション 2: コマンドライン

エージェントを直接実行します:

python -m search

これで、YouTube 動画の検索を依頼することで、エージェントと対話できます。

クエリの例:

• 「Google Cloud Next 25 に関する動画を検索して」
• 「Python プログラミングに関する YouTube チュートリアルを検索して」
• 「初心者向けの機械学習に関する動画を探して」

🔄 仕組み

実装は次の手順に従います:

1. エージェントの初期化:

   • Ollama でホストされている Gemma 3 モデルへの参照を持つ LlmAgent を作成します
   • 適切な指示でエージェントを構成します
   • エージェントの機能に YouTube 検索ツールを追加します

2. ツールの定義:

   • MCP を通じて YouTube 検索関数を定義します
   • MCP は、モデルがツールと連携するための標準化された方法を提供します
   • ツールは YouTube 検索機能のために SERP API に接続します

3. クエリの処理:

   • ユーザーのクエリがエージェントに渡されます
   • Gemma 3 は、クエリに基づいて YouTube 検索ツールを使用するかどうかを判断します
   • 必要に応じて、モデルは適切な検索クエリを作成します
   • 結果はモデルによって処理およびフォーマットされます

4. 応答の生成:

   • エージェントはすべての情報を処理し、検索結果をフォーマットします
   • 出力は、整形された箇条書きリストとしてユーザーに返されます
   • 各結果には、タイトル、リンク、チャンネル、説明、メタデータが含まれます

📁 プロジェクト構成

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 形式を返した場合に発生します。
   • エラーは litellm/llms/ollama/completion/transformation.py の KeyError: 'name' のように表示されます。
   • 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 に関するさらなる記事については、Arjun Prabhulal on Medium をフォローしてください。

📄 ライセンス

このプロジェクトは自由でオープンなライセンスの下で公開されています。誰でも、商業利用を含むあらゆる目的で、このコードを自由に使用、変更、配布、または基にした開発を行うことができます。制限はありません。