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 デプロイは無効） - リージョン:
us-central1
これにより、メインのエージェント ロジック、テスト、GEMINI.md ガイドを含むプロジェクト ディレクトリ構造が生成されます。新しいディレクトリに移動します。
cd my-agent
4. グラウンディングを構成する
Agent Starter Pack は、AI 支援コーディング ツールにプロジェクトの管理方法を指示する GEMINI.md ファイルを生成します。このファイルを更新して、Google マップ グラウンディングのドキュメントを追加します。
- エディタで
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 ツールと統合パターンを確認する