オレンジ色のケーブルが接続されたパッチパネル
ニュース深掘り

StrandsエージェントとMapLibreを組む地図アプリの落とし穴3つ

目次を見る

ブラウザ上の地図をクリックすると、AIエージェントがその場所を調べて答えてくれる。そんな「会話できる地図」アプリをAWSのマネージドサービスと組んで作る構成が話題になっています。フロントエンドでMapLibre GL JS(WebGLで地図を描画するオープンソースライブラリ)を使い、裏でAIエージェントのフレームワークStrands Agents(AWSが公開しているPython製のエージェント構築フレームワーク)とAmazon Location Service(地図タイルや逆ジオコーディングを提供するAWSのマネージドサービス)を呼び出す仕組みです。

この記事は、地図やジオコーディング機能をフロントエンドに組み込みたいWebエンジニアや、新しいエージェント連携パターンを評価したいフロントエンド担当者に向けた内容です。構成自体はシンプルですが、フロントエンド観点で見ると見落としやすい落とし穴がいくつかあります。実際に試す前に押さえておきたいポイントを整理しました。

何が起きるか:「最寄り1件」しか返らない設計の罠

このアプリの中核機能であるreverse_geocode(逆ジオコーディング、座標から地名や施設名を引く処理)は、Amazon Location ServiceのPlaces APIを呼び出して「最も近い1件」だけを返す仕様になっています。

ここに落とし穴があります。たとえばニューヨークのエンパイア・ステート・ビルディングをクリックすると、最寄りの候補はビルそのものではなく、わずか4メートル離れた「観光ツアーの受付窓口」になることがあります。ユーザーが期待する「ビルの名前」が一発で返らないわけです。

この問題を補うために、構成ではfind_nearby_places(周辺検索)という別のツールをエージェントに追加で呼ばせています。先の例では18メートル先に「観光名所」カテゴリのエンパイア・ステート・ビルディングが見つかり、エージェントはそちらを採用して報告します。

さらに海上など何も候補がない地点をクリックすると、両方のAPI呼び出しが空振りし、エージェントは「情報がありません」という一文だけを返す設計です。フロントエンド側でリンクやカード表示を前提に実装していると、この「空応答」のハンドリングを忘れがちです。

なぜ起きるか:地図UIとAPIの設計思想のズレ

原因を段階的に分解すると、3つの層に分かれます。

1つ目は、逆ジオコーディングAPI自体の設計思想です。Amazon Location Serviceに限らず、多くの逆ジオコーディングAPIは「座標に最も近い住所データ」を返すために作られており、「ユーザーが意図したランドマーク」を返すようには最適化されていません。住所検索とランドマーク検索は似て非なるタスクです。

2つ目は、地図タイルのクリック座標の精度です。MapLibre GL JSでクリックイベントを取得すると、ピクセル座標から緯度経度への変換を経るため、ズームレベルによっては数メートル単位の誤差が生じます。ビルの輪郭ギリギリをクリックしたつもりでも、実際には隣接する別の施設の方が近いと判定されることがあります。

3つ目は、エージェントの自律的な判断に処理を委ねている構成そのものです。このアプリではエージェントが「reverse_geocodeの結果が気に入らなければfind_nearby_placesを呼ぶ」という判断を自分で行います。つまり、どのツールがいつ呼ばれるかはプロンプトとモデル(Amazon Bedrock経由のClaude Haiku)の挙動に依存し、フロントエンド側のコードだけを読んでも処理フローを完全には予測できません。

自分のプロジェクトが該当するか確認する方法

既存のプロジェクトでこの落とし穴に該当するかどうかは、以下の観点で確認できます。

  • 地図上のクリックやタップで座標を取得し、何らかの逆ジオコーディングAPIに投げている処理があるか(コードベースでreverse_geocodeやgeocode、placesといった関数名・API名を検索)
  • 使っている地図ライブラリのバージョンを確認する(package.jsonのmaplibre-glのバージョン、またはPython側ならrequirements.txtであればstrands-agentsや関連パッケージのバージョン行)
  • API呼び出しの結果が「0件」だった場合のUI分岐が実装されているか(空配列・nullを受け取ったときの表示ロジックの有無)
  • LLM(大規模言語モデル)にツール呼び出しの判断を委ねている箇所があるかどうか。ツール呼び出しのログやトレースを吐く設定になっているか

AWSのCLIを使っている場合は、まず資格情報と接続先を確認しておくと以降の検証がスムーズです。

aws configure
aws sts get-caller-identity

このコマンドで現在どのAWSアカウント・リージョンに向けて呼び出しているかが分かります。地図タイルやPlaces APIの課金はリクエスト単位なので、意図しないアカウントに向けて大量にクリックテストを行うと、思わぬ請求につながる点も確認しておきたいところです。

対策の手順

対策は大きく3段階に分けられます。

1. フォールバックのツール呼び出しを明示的に用意する

reverse_geocode一発で返す設計のままにせず、結果の距離が一定のしきい値(たとえば10メートル以内など)を超えた場合に、周辺検索のAPIを追加で呼ぶロジックをアプリ側にも持たせておくと安全です。エージェントの自律判断だけに頼らず、フロントエンド・バックエンドのどちらかで最低限のバリデーションを挟む形です。

2. 空応答のUIパターンを先に設計する

「候補が見つからない」場合の表示を後回しにせず、最初のワイヤーフレーム段階で用意しておくと手戻りが減ります。シード元の実装では、最初の応答をPlaceReportというPydanticモデル(Pythonのデータ検証ライブラリで定義された型)で検証し、UI側が自由形式のテキストを直接パースしなくて済むようにしています。似た構成を採る場合、フロントエンドとバックエンドの間で返却スキーマを先に固定しておくのが安全です。

3. エージェントのツール呼び出しをトレースできるようにする

Strands AgentsはSSE(Server-Sent Events、サーバーからブラウザへ逐次データを送るしくみ)でツール呼び出しのステップを順番に流す設計になっています。フロントエンドでこのイベントをログに出すか、開発者ツールのネットワークタブで観察できるようにしておくと、「なぜその場所が返ってきたか」を後から追いやすくなります。

git clone https://github.com/lswans/reverse-geocode-agent.git
cd reverse-geocode-agent
python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

上記はローカルで構成を再現するための最小セットです。インフラのプロビジョニングは不要で、呼び出し課金のみという点も事前に把握しておくと検証のハードルが下がります。

まとめ

地図クリックからAIエージェントが回答を返す構成は、フロントエンドの実装自体はMapLibre GL JSとFastAPIの組み合わせで比較的シンプルです。

ただし、逆ジオコーディングAPIが「最寄り1件」しか返さない設計である点、地図クリック座標の誤差、エージェントの自律判断に処理フローが依存する点の3つは、事前に押さえておきたい落とし穴です。

既存プロジェクトを見直す際は、まず座標から地名を引く処理を洗い出し、空応答時のUI分岐があるかどうかをチェックしてみてください。そのうえでツール呼び出しのログを可視化しておくと、挙動のブレに気づきやすくなります。

参考

Reverse-Geocoding with Strands and Amazon Location Service

AI 駆動開発のご相談は forva AI へ。

まずはお気軽にどうぞ。