MCP AI Agent with Google ADK, Google Maps, and Opik

Google ADK、Google Maps、Opik を使用した MCP AI エージェント

デモ動画

このプロジェクトでは、Google Agent Development Kit（ADK）、OpenAI の GPT-4o モデル、Google Maps MCP サーバー、および Comet.ml を利用した可観測性のための Opik を使用して、AI エージェントを作成する方法を紹介します。

このプロジェクトの主な目的は、エージェント開発の原則や、Model Context Protocol の実践的な適用方法、そしてそのツールやサービスを AI エージェントに統合して、トレーニングデータを超える能力を実現する方法への理解を深めることです。

このプロジェクトは、Santiago Valdarrama 氏による YouTube のチュートリアルから多くの着想を得ています。

• 動画： Google の Agent Development Kit（ADK）で AI エージェントを構築する
• リポジトリ： svpino/google-adk-sample

目次

• 主な技術
  • Google Agent Development Kit（ADK）
  • Opik と CometML
  • Model Context Protocol（MCP）
  • Google Maps MCP サーバー
• プロジェクトの構成
• プロジェクトのセットアップとインストール
  • 前提条件
  • インストール手順
  • 環境変数
  • エージェントの実行
• スクリーンショットと使い方
  • ADK Web UI
  • ツールを使用するエージェント（経路案内）
  • 会話イベントとツールグラフ
  • Opik（CometML）トレーシング
• コードの詳細解説（agent.py）
  • インポートとセットアップ
  • エージェントの定義
  • ツールの設定
  • 可観測性コールバック
• 作者
• ライセンス

主な技術

Google Agent Development Kit（ADK）

Google Agent Development Kit（ADK） は、LLM を活用する AI エージェントの開発を簡素化するために設計された Python フレームワークです。LiteLlm ライブラリとの統合により、OpenAI、Anthropic、Cohere などのプロバイダーが提供する LLM に加え、ツール、メモリ、エージェントのオーケストレーションを利用できます。また、エージェントとの対話やデバッグに使用できる Web UI も備えています。

Opik & CometML

Opik は、Comet が開発した LLM アプリケーション向けのオープンソースのオブザーバビリティソリューションです。AI エージェント内のやり取りについて、トレース、可視化、デバッグができます。これには、LLM 呼び出し、ツールの使用、その他の操作が含まれます。 このプロジェクトでは、エージェントの動作を詳細な UI で確認できるよう、Opik はトレースを CometML に送信するよう設定されています。

Model Context Protocol (MCP)

Model Context Protocol (MCP) は、アプリケーションが LLM にコンテキストを提供し、さまざまなデータソースやツールに接続する方法を標準化するオープンプロトコルです。ツールの説明、呼び出し、応答のスキーマを定義します。これにより、異なる LLM システムやツールプロバイダー間の相互運用が可能になります。

Google Maps MCP サーバー

Google Maps MCP Server は、Google Maps Platform API を MCP ツールとして公開する Node.js アプリケーションです。これにより、ADK エージェントは Google Maps の機能を簡単に活用し、より関連性が高く、コンテキストを考慮した応答を提供できます。

• 実行方法： このプロジェクトの設定に従い、ADK の MCPToolset は、サーバーがまだ実行されていない場合に npx を使用して自動的に起動できます。
• 公開される主なツール：
  • maps_directions：車、徒歩、自転車でのルートを取得します。
  • maps_geocode：住所を地理座標に変換します。
  • maps_reverse_geocode：地理座標を住所に変換します。
  • maps_elevation：指定した座標の標高を取得します。
  • maps_search_places：場所（レストラン、ランドマークなど）を検索します。
  • maps_place_details：特定の場所に関する詳細情報を取得します。
  • maps_distance_matrix：複数の出発地と目的地の間の移動時間と距離を計算します。

プロジェクト構成

.
├── assets
│   └── screenshots
│       ├── interface.png
│       ├── maps_direction_tool_input_output.png
│       ├── maps_direction_tool_opik.png
│       ├── maps_direction_tool.png
│       ├── maps_directions_tool_events.png
│       ├── maps_elevation_tool.png
│       ├── maps_place_details_event.png
│       ├── maps_reverse_geocode_event.png
│       ├── opik_overall_input_output.png
|       ├── adk.png
|       ├── mcp.png
│       └── opik_traces.png
├── examples
│   └── agent_conversation.yaml
├── LICENSE
├── mcp_agent
│   ├── __init__.py
│   └── agent.py
├── pyproject.toml
├── README.md
└── uv.lock

プロジェクトのセットアップとインストール

前提条件

• Python 3.11
• uv（Python パッケージおよび仮想環境マネージャー）
• Node.js および npm / npx（Google Maps MCP サーバーの実行に必要です。ADK は npx 経由でサーバーを起動します）
• Google Maps Platform API キー？
• OpenAI API キー。
• CometML API キー、プロジェクト ID、ワークスペース。

インストール手順

1. リポジトリをクローンします：

   git clone https://github.com/luuisotorres/mcp-ai-agent.git
   cd mcp-ai-agent
   

2. UV を使用して仮想環境を作成し、同期します：

   uv venv  # 仮想環境を作成します（例：.venv）
   uv sync  # pyproject.toml から依存関係をインストールします
   source .venv/bin/activate # Windows では `.\.venv\Scripts\activate` を使用します
   

3. 環境変数を設定します： サンプル環境ファイルをコピーし、認証情報を記入します：

   cp .env.example .env
   

   次に、.env を編集して実際の API キーを設定します。

環境変数

GOOGLE_MAPS_PLATFORM_API_KEY="your-google-maps-api-key"
OPENAI_API_KEY="your-openai-api-key"
COMET_API_KEY="your-comet-api-key"
COMET_WORKSPACE="your-comet-workspace"
COMET_PROJECT_NAME="your-comet-project-name"

.env ファイルには、次の内容を記載します：

• GOOGLE_MAPS_PLATFORM_API_KEY：Google Maps Platform API キーです。
  • 用途： Google Maps MCP サーバーが Google Maps API にリクエストを送信できるようにします。
• OPENAI_API_KEY：OpenAI API キーです。
  • 用途： LiteLlm モデルが OpenAI の GPT モデルを使用できるようにします。
• COMET_API_KEY：CometML API キーです。
  • 用途： Opik がトレースを CometML プロジェクトに送信するために使用します。
• COMET_WORKSPACE：CometML ワークスペースです。
• COMET_PROJECT_NAME：トレースを保存する CometML プロジェクト名です。

エージェントの実行

セットアップが完了したら、ADK Web UI を起動します。

uv run adk web

このコマンドを実行すると、次の処理が行われます。

1. FastAPI サーバーを起動します。
2. エージェントと対話するための Web インターフェースを http://127.0.0.1:8000 で提供します。
3. agent.py の MCPToolset は、エージェントがツールを使う必要があるときに、npx を介して Google Maps MCP サーバーを自動的に起動するよう設定されています。

スクリーンショットと使い方

ADK Web UI

uv run adk web を実行して http://127.0.0.1:8000（またはターミナルに表示されたポート）にアクセスすると、ADK Web UI が表示されます。エージェント（この例では mcp_agent）を選択して、会話を開始できます。

（スクリーンショット 1：チャット入力欄がある ADK Web UI の初期画面。） キャプション：エージェントにメッセージを入力できる ADK Web UI のメインインターフェースです。

ツールを使うエージェント

エージェントは、Google Maps MCP サーバーのツールを使って、道順、場所の詳細、標高などのリクエストを理解できます。

例：道順の取得 「São Paulo から Campinas まで車で行くにはどうすればよいですか？」という質問に対して、エージェントは曲がり角ごとの道順を回答します。

（スクリーンショット 2：maps_directions ツールを使うエージェント。） キャプション：エージェントが maps_directions ツールを正常に使い、チャットインターフェースで車での道順を案内しています。

例：場所の詳細の取得 エージェントは、ランドマークのレビューやその他の情報を取得できます。

（スクリーンショット 3：エッフェル塔のレビューを取得するために maps_place_details を使うエージェント。） キャプション：エージェントがエッフェル塔のレビューを取得して表示し、maps_place_details ツールの使用方法と出力を示しています。

例：標高の取得 エージェントは、指定された座標の標高を提示できます。

（スクリーンショット 4：maps_elevation ツールを使うエージェント。） キャプション：エージェントが maps_elevation ツールを使って、指定された座標の標高を提示しています。

会話イベントとツールの呼び出し

ADK Web UI には「Events」（または「Trace」）タブがあり、会話の流れを確認できます。エージェントが実行した関数呼び出しと、ツールから受け取った応答も確認できます。

例：maps_reverse_geocode イベント エージェントが maps_reverse_geocode ツールを呼び出す様子を示します。

（スクリーンショット 5：maps_reverse_geocode のイベント表示。） キャプション：maps_reverse_geocode の functionCall と args、Metadata の詳細を示すイベント表示です。

例：maps_directions のイベントフロー maps_directions ツールを呼び出したときのイベントの流れを示します。

（スクリーンショット 6：maps_directions ツールのイベント表示。） キャプション：ADK UI の「Events」タブに、maps_directions ツールの呼び出しの詳細が表示されています。

Opik（CometML）のトレース

Opik は CometML と連携し、エージェントの実行を詳細にトレースして、LLM 呼び出し、ツールの使用状況、全体的なパフォーマンスに関する分析情報を提供します。

Opik の全体的なトレース プロジェクトで記録されたすべてのインタラクションの一覧です。

(スクリーンショット 7：mcp-ai-agent プロジェクトの CometML におけるトレースの概要。) キャプション：さまざまなエージェントとのインタラクションについて Opik が記録したトレースの一覧を表示する CometML の UI。

maps_direction_tool の詳細な Opik トレース LLM 呼び出しと maps_direction_tool の呼び出しを示す、特定のトレースです。

(スクリーンショット 8：maps_directions ツールが関わる単一のトレースの詳細ビュー。) キャプション：CometML の Opik トレースの詳細ビュー。LLM 呼び出しやツールとのインタラクションを含む、maps_directions リクエストの一連の操作を表示しています。

Opik の入出力 YAML LLM 呼び出しやツールとのインタラクションに関する詳細なリクエストおよびレスポンスデータを YAML 形式で表示します。

(スクリーンショット 9：Opik における maps_direction ツール呼び出しの入出力詳細。) キャプション：CometML の Opik トレース内にある「Input/Output」タブ。会話全体のリクエストとレスポンスを YAML 形式で表示しています。

これらのトレースは、デバッグ、エージェントの動作の把握、パフォーマンスの最適化に非常に役立ちます。

注： この会話の YAML ファイル全体は examples/agent_conversation.yaml にあります。

コードの詳細解説（agent.py）

インポートとセットアップ

まず、ADK、環境設定、可観測性に必要なパッケージをインポートします。

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
from google.adk.tools.mcp_tool.mcp_toolset import (
    MCPToolset,
    StdioServerParameters
)
import os
from dotenv import load_dotenv
import opik
from opik.integrations.adk import OpikTracer

これにより、エージェントのロジックの基盤が整います。

環境設定

ここでは API キーを読み込み、可観測性を設定します。

load_dotenv()
opik.configure(use_local=False)
tracer = OpikTracer()
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_PLATFORM_API_KEY")

エージェントの定義

OpenAI の GPT-4o モデルと、ADK と OpenAI を連携するための LiteLlm ライブラリを使用して、LlmAgent で ADK Agent を初期化します。

root_agent = LlmAgent(
    model=LiteLlm(model="openai/gpt-4o"),
    name="openai_agent",
    description="An intelligent mapping assistant that provides driving, walking, and public transportation directions...",
    instruction="When the user asks for routes, travel times, or directions between locations..."

ツールの設定

ここでは Google Maps MCP Server との連携を定義します。

tools=[
    MCPToolset(
        connection_params=StdioServerParameters(
            command="npx",
            args=[
                "-y",
                "@modelcontextprotocol/server-google-maps"
            ],
            env={
                "GOOGLE_MAPS_API_KEY": GOOGLE_MAPS_API_KEY
            },
        ),
    )
],

これにより、npx を使って MCP サーバーを起動し、すべての Google Maps ツールをエージェントで利用できるようにします。

可観測性コールバック

最後に、エージェントのライフサイクル全体を記録するため、Opik のトレースコールバックを追加します。

before_agent_callback=tracer.before_agent_callback,
after_agent_callback=tracer.after_agent_callback,
before_model_callback=tracer.before_model_callback,
after_model_callback=tracer.after_model_callback,
before_tool_callback=tracer.before_tool_callback,
after_tool_callback=tracer.after_tool_callback,
)

これにより、エージェントが処理するすべてのインタラクションを詳細に把握できます。

作成者

Luis Fernando Torres

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については、LICENSE ファイルをご覧ください。