Обеспечение связи агентов ИИ с реальным геопространственным контекстом с помощью Maps Grounding Lite MCP.

Создание агентов искусственного интеллекта представляет собой значительный шаг вперед в разработке программного обеспечения, позволяя системам выполнять сложные рассуждения и работать с большей автономностью. Однако базовые модели, лежащие в основе этих систем, естественно, ограничены данными для обучения. Без внешнего контекста им не хватает информации о реальных условиях, таких как текущая погода за окном, открыт ли сейчас местный магазин или наиболее эффективный маршрут до места назначения.

В этом документе подробно описано, как преодолеть разрыв между статическим мышлением и динамической реальностью, используя для построения моделей на основе ИИ надежные геопространственные данные из Google Maps. Вы узнаете, почему пространственная привязка имеет решающее значение для решения реальных задач, как протокол контекста модели (MCP) упрощает интеграцию инструментов и как создать агента планирования поездок, используя Google Maps Grounding Lite MCP.

Агент по планированию поездок, работающий с картами (MCP)

Зачем агентам нужна привязка картографических данных?

Переход от традиционного программного обеспечения к агентным рабочим процессам — это сдвиг от детерминированного проектирования к вероятностной оркестровке. Мы переходим от систем, которые просто знают что-то, к проактивным механизмам выполнения, которые действительно что-то делают. Когда приложение переступает эту черту и предпринимает действия в физическом мире, требования к точности полностью меняются.

Большие языковые модели (LLM) понимают логику, но их внутренняя память представляет собой исторический снимок. Например, если агент, управляющий цепочкой поставок, неверно подтверждает наличие поставщика или маршрут, это приводит к растрате топлива, нарушению соглашений об уровне обслуживания (SLA) и реальным сбоям в работе бизнеса. А в многоагентных архитектурах возникает проблема каскадных галлюцинаций. Если один агент в цепочке выдает галлюцинацию и передает неверные данные второму агенту, вся система начинает принимать реальные решения, основанные на лжи. Автономия без истины становится огромным недостатком.

Функция «Приземление» требует, чтобы агент выходил за рамки своих обучающих весов. Заставляя ИИ получать проверяемые, актуальные данные — такие как данные о местах и ​​данные о маршрутах — вы предоставляете агенту возможность наблюдать и слышать в режиме реального времени, превращая статистическое предположение в обоснованное оперативное решение.

Почему MCP

Протокол контекста модели (MCP) — это открытый стандарт, разработанный для упрощения интеграции инструментов и данных по принципу «подключи и работай».

Исторически сложилось так, что для подключения модели ИИ к внешним API требовалось написание жёстких, специализированных оберток. Приходилось вручную обрабатывать форматирование, анализ ошибок и перевод вызовов инструментов для каждой отдельной функции.

MCP стандартизирует этот интеграционный слой. Внедрение клиента MCP позволяет вашему приложению динамически обнаруживать и выполнять предоставляемые сервером инструменты по единому протоколу. Это смещает акцент разработчика с написания повторяющейся логики интеграции API на проектирование высокоуровневых агентных сетей.

Google Maps Grounding Lite MCP

Google Maps Grounding Lite MCP — это полностью управляемый сервер MCP, размещенный на серверах Google, который может быть интегрирован непосредственно в любую совместимую агентскую среду.

В настоящее время сервер предоставляет три основных инструмента для заземления:

• Поиск мест : Запросите информацию о местах и ​​получите сгенерированные искусственным интеллектом сводные данные о местах, а также идентификаторы мест, координаты широты и долготы и ссылки на Google Maps для каждого из мест, включенных в сводку. Вы можете использовать полученные идентификаторы мест и координаты широты и долготы с другими API платформы Google Maps для отображения мест на карте.
• Поиск погоды : Запросите информацию о погоде и получите текущие условия, почасовые и суточные прогнозы.
• Расчет маршрутов : Запрос информации о маршрутах движения на автомобиле или пешком между двумя точками и получение информации о расстоянии и продолжительности маршрута.

Для доступа к сервису можно использовать либо ключ API, либо OAuth. Google Maps Platform предоставляет бесплатный демонстрационный ключ API, специально разработанный для того, чтобы помочь разработчикам немедленно начать прототипирование.

Карты, заземление, архитектура MCP

Рекомендации по интеграции карт и привязке MCP

Чтобы максимально повысить релевантность данных и исключить структурные искажения, постройте инструкции для системы вашего агента на основе следующих основных стратегий: * Будьте четкими и конкретными : инструктируйте агента использовать точные местоположения. «Центральный парк, Нью-Йорк» дает лучшие результаты, чем «Нью-Йорк», так же как «Париж, Франция» предотвращает путаницу с Парижем, штат Техас.

• Разбивайте запросы на более простые категории : для расплывчатых запросов, таких как «идеи для свидания», предложите агенту разбить задачу на конкретные подзапросы, например, «романтичные рестораны», «кинотеатры» или «коктейль-бары».

• Сначала поиск, затем исследование : сначала проведите общий поиск (например, «японские рестораны с доступными входами, открытые по воскресеньям»). Предложите пользователю варианты, а затем выполните дополнительный запрос для получения конкретных сведений, таких как номер телефона выбранного заведения.

• Никогда не фантазируйте об идентификаторах мест : идентификаторы мест являются важнейшим связующим звеном между сервисами платформы Google Maps. Убедитесь, что ваш агент знает, что он должен использовать только идентификаторы мест, явно возвращаемые инструментом search_places, а не пытаться генерировать свои собственные.

Внедрите систему планирования поездок с помощью Google ADK.

В этом разделе показано, как создать агента по планированию путешествий, используя фреймворк Google Agent Development Kit (ADK). Если у вас не установлен ADK, см. документацию для разработчиков Google ADK .

Интеграция сервера Maps MCP в агентскую платформу, такую ​​как ADK, довольно проста. ADK берет на себя сложные задачи управления контекстом, позволяя вам сосредоточиться на поведении агента.

Пример проекта имеет следующую структуру:

travel-concierge-google-maps-mcp/
├── travel_planner_agent/
    ├── agent.py      # main agent code
    ├── .env          # API keys
    ├── __init__.py
    ├── skills/travel-concierge/
      ├── SKILL.md    # Agent skill

Пример файла agent.py. Отредактируйте его в соответствии с вашими потребностями.

import os
import pathlib
import logging
from datetime import date
from dotenv import load_dotenv

from google.adk.agents.llm_agent import Agent
from google.adk.skills import load_skill_from_dir
from google.adk.tools import skill_toolset
from google.adk.tools.mcp_tool import McpToolset
from google.adk.planners import BuiltInPlanner
from google.genai import types
from google.adk.tools.mcp_tool.mcp_session_manager
 import StreamableHTTPConnectionParams

load_dotenv()
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    raise ValueError("Missing GOOGLE_MAPS_API_KEY environment variable.")

current_date = date.today().strftime("%A, %B %d, %Y")

# AGENT & TOOL SETUP
BASE_SYSTEM_INSTRUCTION = f"""
You are a Premium Travel Orchestrator. Your sole purpose is to assist users with travel planning, location discovery, route mapping, weather checks, and culinary/cultural recommendations. The current system date is {current_date}.

# 1. OUT-OF-DOMAIN PROTOCOL (Strict Refusal)
You are strictly forbidden from answering queries unrelated to travel, geography, food, hospitality, or local experiences.
If a user asks about coding (e.g., Python bugs), math, writing essays, or general non-travel trivia:
- Politely decline.
- Explicitly state that your expertise is limited to travel and local discovery.
- Pivot by asking if they need help planning a trip or finding a great local spot.

# 2. TANGENTIAL KNOWLEDGE PROTOCOL (The "Tiramisu" Rule)
If a user asks a factual question about food, a cultural item, or a historical concept that *can* be tied to a physical location (e.g., "What is tiramisu?", "What is Gothic architecture?"):
- Provide a brief, helpful 1-2 sentence explanation of the concept.
- IMMEDIATELY pivot to your primary domain. Ask the user for their current location or target city so you can search for the best places to experience or eat that item.

# 3. TOOL EXECUTION BOUNDARIES
- NEVER call `lookup_weather` for general history, trivia, or factual questions.
- ONLY call `lookup_weather` if the user explicitly asks for the forecast, OR if they have confirmed they are actively planning an itinerary/trip for a specific date and destination.
"""

travel_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "travel-concierge"
)

maps_mcp_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://mapstools.googleapis.com/mcp",
        headers={
            "X-Goog-Api-Key": GOOGLE_MAPS_API_KEY,
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream"
        }
    )
)

my_skill_toolset = skill_toolset.SkillToolset(
    skills=[travel_skill],
    additional_tools=[maps_mcp_toolset]
)

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description="A highly capable assistant leveraging specialized modular skills and spatial tools.",
    instruction=BASE_SYSTEM_INSTRUCTION,
    planner=BuiltInPlanner(        
        thinking_config=types.ThinkingConfig(
            include_thoughts=True
        )
    ),
    tools=[my_skill_toolset]
)

Пример файла SKILL.md. Отредактируйте его в соответствии с вашими потребностями.

name: travel-concierge
description:
  Accesses real-time spatial data, weather, and traffic routing to design accurate itineraries and provide location-based information.
  Use when: A user is planning a trip, creating a travel itinerary, mapping a route, asking about a city's history, discovering local foods, exploring basic geography trivia, or inquiring about the weather.
  Dont use for: Tasks completely unrelated to travel, locations, geography, or weather, such as coding assistance, mathematical calculations, or personal finance.

metadata:
  adk_additional_tools:
    - search_places
    - lookup_weather
    - compute_routes
---

# Travel Concierge Workflow

You act as an elite, deeply consultative travel planner. You are responsible for designing logistically sound travel plans by strictly prioritizing your toolset over pre-trained memory. 

To deliver a premium experience, you must manage the interaction in two distinct phases: Discovery and Execution.

## Phase 1: Discovery Dialogue & Briefing (First Turn)
When a user initiates a request but leaves critical logistical variables open, **do NOT generate a complete multi-stop itinerary or directions link immediately.** Instead, build a warm, conversational dialogue to lock in the baseline parameters.

1. **Conditional Weather Context Hook:** ONLY call `lookup_weather` if the user is actively planning a trip to a specific location on a specific date, OR if they explicitly ask for the weather. DO NOT check the weather for general questions about a city's history or local foods. If you do check the weather for a trip, share a brief summary of the conditions to justify your upcoming line of questioning.
2. **Targeted Consultation (Ask 2-3 Friendly Questions):**
   - **Verify Arrival Point & Terminal:** Never assume an airport arrival. If they state an arrival time but no explicit location, set an internal baseline but explicitly ask them to confirm their exact station or airport terminal. **If they confirm an airport arrival, strictly verify whether it is a Domestic or International flight**, as clearing international customs and immigration requires adding a 60-to-90-minute buffer to the initial travel time before scheduling the first venue.
   - **Verify User Preferences:** If food or activity interests are ambiguous or partial (e.g., "coffee and seafood"), acknowledge these directly and ask about their preferred style or pacing (e.g., casual local markets vs. seated upscale dining).
   - **Anchor Point Checking:** Always ask if there is a specific bucket-list venue or seasonal sight they absolutely must visit so you can build the fixed timeline around it.

## Phase 2: Location Extraction & Validation
- Use `search_places` to verify destinations, opening hours, and location accuracy.
- **CRITICAL INPUT RULE:** You must ensure the `text_query` parameter contains explicit location keywords. If the user mentions "boutique hotels" or "seafood dinner", you must modify the query to include the city (e.g., text_query="boutique hotels in Sydney, Australia").

## Phase 3: Tool Execution & Itinerary Reveal (Subsequent Turns)
Once the user responds with their specific logistics, construct the definitive itinerary using your spatial grounding tools. When preferences remain broad, default to highly rated venues that match the verified weather conditions and current seasonality.

### 1. Location Validation (`search_places`)
- Verify all destinations, opening hours, and exact addresses.
- **CRITICAL INPUT RULE:** You must ensure the `text_query` parameter contains explicit location keywords. If the user requests "boutique hotels" or "seafood lunch", modify the query to append the target city/region (e.g., `text_query="seafood lunch in Sydney, Australia"`).

### 2. Logistical Reality (`compute_routes`)
- Ensure consecutive stops are logically possible by checking travel times and distances.
- Pass both `origin` and `destination` using verified addresses or Place IDs. If either is missing, halt and ask for clarification.
- Do NOT hallucinate Place ID. You must use the Place ID provided by `search_places`.


### 3. Itinerary Output Formatting
- **Route to Next Stop:** Between every single consecutive itinerary stop, you MUST output a dedicated sub-bullet detailing the transit path.
- This bullet must explicitly state the suggested travel mode (Walk, Transit, or Drive), the exact travel time in minutes verified by `compute_routes`, and a brief path description (e.g., *"Route to Next Stop: 12-minute walk via Market St"*).
- **Attribution:** Include inline or bracketed Google Maps URLs for recommended venues using data derived from the tool's attribution payloads. Do not guess links.

### 4. Multi-Stop Directions Link Generation
At the absolute end of your finalized itinerary response, compile all planned locations into a single, functional Google Maps Directions URL.
- **Format Constraint:** Build the URL using the base string: `https://www.google.com/maps/dir/`
- Append each venue name and full address sequentially, separated by a forward slash `/`, replacing spaces with `+` and encoding URL parameters where necessary. 
- Example format: `https://www.google.com/maps/dir/Venue+One,+Address/Venue+Two,+Address/Venue+Three,+Address/`
- Present this link prominently with clear anchor text.

## Phase 4: Output Formatting & Source Attribution (CRITICAL)
- You must comply strictly with Google Maps Platform display guidelines. 
- Every grounded piece of information (Places, Weather, Routes) must be immediately followed by its supporting source.
- For place details extracted via `search_places`, always map and output the exact URL provided in the `places.googleMapsLinks.placeUrl` payload. Do not invent links.

init.py

from . import agent

Запустите веб-версию AdK и взаимодействуйте.

Чтобы запустить веб-интерфейс ADK по умолчанию, выполните следующую команду в каталоге проекта travel-concierge-google-maps-mcp:

adk web

Взаимодействуйте в пользовательском интерфейсе:

• Загрузите пользовательский интерфейс по адресу http://127.0.0.1:8000 в браузере.
• Попробуйте использовать такие подсказки:
  • «В субботу я буду в Сан-Франциско. Организуйте для меня однодневную поездку».
  • «Найдите кофейни рядом с парком Голден Гейт и покажите мне основные блюда из их меню».
  • «Получите маршрут от GooglePlex до аэропорта SFO».

Когда агент получает запрос, планировщик оценивает намерения пользователя. Он распознает необходимость в пространственных данных и данных о погоде и автоматически запускает инструменты lookup_weather, search_places и compute_routes, используя сервер MCP. Затем агент формирует для пользователя маршрут, основанный на фактических данных.

Заключение

Переход к агентному искусственному интеллекту открывает совершенно новые возможности в логистике, туризме и розничной торговле. Однако для подлинной автономии необходима надежная основа, основанная на достоверной информации.

Используя протокол контекста модели (Model Context Protocol) совместно с Google Maps Grounding Lite, вы устраняете сложности, связанные с интеграцией специализированных API, и предоставляете своим агентам необходимую информацию и данные в режиме реального времени. Привязка моделей к реальным пространственным данным гарантирует, что они будут принимать оперативные решения, основываясь на том, что происходит в физическом мире прямо сейчас, а не на застывшем снимке из обучающих данных.

Следующие действия

• Ознакомьтесь с документацией для разработчиков Maps Grounding MCP .
• Получите демо-ключ API .
• Узнайте, как развернуть своего агента .

Основные авторы:

Тереза ​​Цинь | Инженер по разработке и внедрению платформы Google Maps