1. はじめに
この Codelab では、Agent Development Kit（ADK）を使用して旅行プランニング エージェントを構築し、Google マップでグラウンディングします。Google マップの実際のデータを利用して、エージェントに景色の良いルートやおすすめのレストランを生成するよう指示します。
演習内容
- Agent Starter Pack を使用してエージェント プロジェクトを初期化する
- Google マップ グラウンディング ツールを使用するようにエージェントを構成する
- ウェブ インターフェースを使用して、作成されたエージェントをローカルでテストする
必要なもの
- ウェブブラウザ（Chrome など）
- 課金を有効にした Google Cloud プロジェクト
この Codelab は、Python と Google Cloud にある程度精通しているが、必ずしもエキスパートではない中級レベルのデベロッパーを対象としています。
2. 始める前に
Google Cloud プロジェクトの作成
- Google Cloud コンソールのプロジェクト セレクタ ページで、Google Cloud プロジェクトを選択または作成します。
- Cloud プロジェクトに対して課金が有効になっていることを確認します。プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。
Cloud Shell の起動
- 認証を確認します。
gcloud auth list
- プロジェクトを確認します。
gcloud config get project
- 必要に応じて設定します。
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
API を有効にする
次のコマンドを実行して、必要な API をすべて有効にします。
gcloud services enable \
aiplatform.googleapis.com
3. Agent Starter Pack をインストールする
ADK プロジェクトを開始する最も簡単な方法は、Agent Starter Pack を使用することです。Google Cloud Agent Starter Pack は、Google Cloud でプロダクション レディな生成 AI エージェントの開発とデプロイを加速するように設計されたオープンソースのコマンドライン インターフェース（CLI）ツールです。
uvがインストールされていることを確認し、create コマンドを実行して新しいエージェント プロジェクトを初期化します。
uvx agent-starter-pack create
- プロンプトが表示されたら、次のオプションを指定して、React フロントエンドを使用したローカル開発用にプロジェクトを構成します。
- エージェント テンプレート:
adk（シンプルな React エージェント） - デプロイ:
none（現時点では Cloud Deployment は無効） - リージョン:
us-central1
これにより、メイン エージェント ロジック、テスト、GEMINI.md ガイドを含むプロジェクト ディレクトリ構造が生成されます。新しいディレクトリに移動します。
cd my-agent
4. 根拠づけを構成する
Agent Starter Pack は、プロジェクトの管理方法を AI 支援コーディング ツールに指示する GEMINI.md ファイルを生成します。このドキュメントは、Google Maps Grounding のドキュメントを含むように更新されます。
- エディタで
GEMINI.mdを開きます。 ## Reference Documentationセクションの下に次の参照リンクを追加します。
- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps
このコンテキストは、AI コーディング アシスタントがグラウンディング機能を理解するのに役立ちます。
5. エージェントを更新する
次に、Google マップのグラウンディング ツールを使用して、旅行プランナーとして機能するようにエージェントを構成します。
app/agent.pyファイルを開きます。app/agent.pyの内容全体を次のコードに置き換えます。
"""Agent application for the itinerary planner codelab."""
import os
import google.auth
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.tools import google_maps_grounding
from google.genai import types
# Authenticate and set environment variables
_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
# Define the root agent
root_agent = Agent(
name="itinerary_planner_agent",
model=Gemini(
model="gemini-2.5-flash",
retry_options=types.HttpRetryOptions(attempts=3),
),
instruction=(
"You are an itinerary planner agent. Help users plan their trips by"
" recommending restaurants and scenic routes. Use the"
" google_maps_grounding tool to get both restaurant recommendations and"
" route recommendations based on user preferences. When calling for"
" restaurant recommendation, prompt the tool to tell you about the vibe"
" of the place. When calling for routes with multiple legs, describe"
" each of those legs with a brief sentence. Always describe the key"
" landmarks along the route in one brief sentence."
),
# Add the Google Maps Grounding tool to the agent
tools=[google_maps_grounding],
)
app = App(
root_agent=root_agent,
name="app",
)
このコードは、google_maps_grounding ツールを使用して場所とルートに関する現在の情報を取得する gemini-2.5-flash ベースのエージェントを構成します。
使用可能なすべてのモデルを表示するには、Vertex AI のドキュメントをご覧ください。
6. エージェントを実行する
エージェント ロジックを配置したら、ローカル ウェブ インターフェースでテストしてみましょう。
my-agentディレクトリのルートから、次のコマンドを実行してウェブアプリを起動します。
uv run adk web
仮想環境を使用している場合:
adk web
- ターミナル出力に表示された URL をブラウザで開きます。
- エージェントに質問してテストします。次に例を示します。
- 「サンフランシスコの 1 日の旅程を計画して。おすすめのイタリアン レストランも入れて。」
- 「東京を訪れる予定です。興味深い歴史的建造物と、居心地の良い雰囲気で評価の高いラーメン店を含む旅行プランを教えてください。」
Google マップから直接取得した実際のクチコミやルートの説明が追加された、詳細な旅程のような出力が表示されます。
7. コード内のグラウンディングを検証する
エージェントがマップ グラウンディングを正常に使用していることをプログラムで確認するには、マップ固有のメタデータについてレスポンス イベントを検査します。
エージェントを（テスト スクリプトなどで）実行すると、エージェントは grounding_metadata を含むイベントを生成します。このメタデータ内の grounding_chunks を反復処理して、maps 属性を確認できます。
自動テストで使用する可能性のあるものと同様に、maps 属性を確認する方法を示す例を次に示します。
async for event in runner.run_async(
user_id="test_user",
session_id=session.id,
new_message=content,
):
if event.grounding_metadata:
if event.grounding_metadata.grounding_chunks:
for chunk in event.grounding_metadata.grounding_chunks:
# Check for the maps attribute to confirm maps grounding
if hasattr(chunk, "maps") and chunk.maps:
print("SUCCESS: Maps grounding chunks detected in the response!")
8. エンコードされたポリラインを抽出する
グラウンディングが発生したことを確認するだけでなく、ルートパスなどの特定のデータを抽出することもできます。マップ グラウンディング ツールがルート情報を返す場合、多くの場合、「エンコードされたポリライン」が含まれます。これは、地図のフロントエンドでルートをレンダリングするために使用できます。
このポリラインは、grounding_chunks の maps 属性内のテキストを確認することで見つけることができます。検出方法の例を次に示します。
async for event in runner.run_async(
user_id="test_user",
session_id=session.id,
new_message=content,
):
if event.grounding_metadata:
if event.grounding_metadata.grounding_chunks:
for chunk in event.grounding_metadata.grounding_chunks:
# Extract the encoded polyline from the maps chunk text
if (
hasattr(chunk, "maps")
and chunk.maps
and hasattr(chunk.maps, "text")
and chunk.maps.text
and "Encoded Polyline" in chunk.maps.text
):
print("SUCCESS: Encoded Polyline detected in the response!")
9. クリーンアップ
Google Cloud アカウントに継続的に課金されないようにするには、この Codelab で作成したリソースを削除します。
- この Codelab 専用のプロジェクトを作成した場合は、完全に削除します。
gcloud projects delete $PROJECT_ID
既存のプロジェクトを使用していて、そのプロジェクトを保持する場合は、削除する特定のリソースはありません。エージェントはローカルで実行され、使用される API はサーバーレスであるためです。
10. 完了
おめでとうございます！これで、Google マップの分析情報を使用して、旅程プランナー エージェントを正常に構築し、グラウンディングしました。
学習した内容
- Agent Starter Pack を使用して新しいエージェントをスキャフォールディングする方法
- ADK エージェント定義にグラウンディング ツールを追加する方法
- 組み込みのウェブ ランナーを使用して ADK エージェントをテストする方法
次のステップ
- 他の ADK ツールと統合パターンを確認する