Получите доступ к дополнительным возможностям инструментов агентов Maps Experience с подпиской Pro. Подробнее о Pro

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

инструменты агента Maps Experience

Инструменты агентов Maps Experience (ранее – Maps Grounding Lite) – это сервис платформы Google Карт с поддержкой протокола контекста модели (MCP) и REST, который позволяет заземлять приложения ИИ с помощью надежных геопространственных данных из Google Карт. Его инструменты позволяют LLM получать доступ к данным о местах, погоде, качестве воздуха, пыльце и маршрутах. Другие инструменты преобразуют названия мест и URL Google Карт в идентификаторы мест. Чтобы попробовать инструменты агентов Maps Experience, включите MCP-сервер в любом инструменте, который поддерживает такие серверы. Вы также можете вызывать каждый инструмент как метод REST. Подробнее о том, как вызывать инструменты с помощью REST…

Инструменты агентов Maps Experience – это один продукт с двумя SKU: Essentials и Pro. Каждый запрос оплачивается по тарифу Essentials, если не используется вариант Pro. В версии Pro можно искать места вдоль маршрута, получать расширенную информацию о местах, больше мест за один поиск, больше промежуточных остановок на маршруте, маршруты с учетом трафика, прогнозы по пыльце и исторические данные о качестве воздуха. Для обеих лицензий используются одни и те же инструменты, сервер MCP, методы REST и учетные данные. Подробнее о версиях Essentials и Pro…

Инструменты

Инструменты агентов Maps Experience позволяют LLM получать доступ к следующим возможностям Google Карт:

Поиск мест. Запрашивайте информацию о местах и получайте краткие пересказы, созданные ИИ. В ответе также содержатся идентификаторы мест, координаты широты и долготы и ссылки на Google Карты для каждого места в сводке. Идентификаторы мест и координаты широты и долготы можно использовать с другими API платформы Google Карт, чтобы показывать места на карте. Чтобы показывать эти места с помощью Places UI Kit без дополнительной платы, используйте токен визуализации данных агента (предварительная версия). С Pro вы можете запрашивать расширенную информацию о местах, например статистику из отзывов, и до 10 мест за запрос.
Поиск вдоль маршрута. Поиск мест вдоль маршрута, заданного с помощью retrieval_token из compute_routes, route_endpoints или encoded_polyline. Вы можете получить сводку, созданную ИИ, информацию о местах, расстояние и время в пути при объезде, а также токен визуализации данных агента (предварительная версия). Каждый запрос search_along_route оплачивается по коду Pro.
Погода. Запрашивайте информацию о погодных условиях в определенном месте, включая текущую погоду, историю за последние 24 часа и почасовой и ежедневный прогноз на срок до 10 дней, а также текущее качество воздуха и прогноз на срок до 4 дней. С версией Pro вы также можете запрашивать ежедневные прогнозы уровня пыльцы на срок до 5 дней (с подробными сведениями о видах растений) и почасовую историю качества воздуха за период до 30 дней.
Расчет маршрутов. Запросите маршрут между пунктами отправления и назначения, при необходимости указав промежуточные остановки. Вы получите расстояние, продолжительность и retrievalToken для DRIVE маршрутов, которые можно передать в search_along_route. В версии Pro маршруты могут учитывать загруженность дорог и включать больше промежуточных остановок.

Примечание. Инструменты агентов Maps Experience не предоставляют пошаговые маршруты или информацию для навигации. Маршруты, рассчитанные без функций Pro, не учитывают дорожную обстановку в реальном времени.
Преобразование названий и Преобразование URL Карт. Преобразуйте названия мест, адреса и URL Google Карт в идентификаторы мест. Подробнее о Resolution API…

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

Essentials и Pro

Essentials и Pro – это два кода одного продукта, а не отдельные продукты или тарифные планы. Запрос оплачивается по тарифу Pro, если в нем используется функция Pro. Все остальные запросы оплачиваются по тарифу Essentials. Параметры Pro – это обычные поля в запросе инструмента, поэтому LLM может использовать их от вашего имени. Агент также может использовать оба SKU в одном разговоре. Например, агент может использовать Essentials, чтобы найти кофейни рядом с достопримечательностью. Затем Gemini Pro может ответить на уточняющий вопрос о фирменных напитках и количестве мест. Для Pro нет отдельного сервера, конечной точки или учетных данных MCP.

Сравнение Essentials, Pro и обоснования с Google Картами

Обоснование с Google Картами – это отдельный продукт. Она встроена в модели Gemini в Gemini API, Google AI Studio и Gemini Enterprise Agent Platform. Модель решает, когда запрашивать Google Карты, и возвращает обоснованные ответы с цитатами. Выберите обоснование с Google Картами, если вы разрабатываете продукт на основе Gemini и хотите, чтобы модель выполняла обоснование. Выберите инструменты агентов Maps Experience для других моделей или фреймворков агентов или для прямого управления каждым вызовом инструмента.

В таблице ниже сравниваются SKU Essentials, SKU Pro и обоснование с Google Картами.

	инструменты агентов Maps Experience		Обоснование с Google Картами
	Essentials SKU (ранее – Maps Grounding Lite)	Pro SKU	Обоснование с Google Картами
Как оплачиваются запросы	Каждый запрос к инструменту, в котором не используется функция Pro	Каждый запрос к `search_along_route` или любому другому инструменту, использующему Pro. Подробнее о том, что оплачивается в рамках лицензии Pro…	Каждый запрос к Google Картам или обоснованный запрос в зависимости от платформы и модели.
Модели и платформы	Любая модель или фреймворк агента, поддерживающие MCP или способные вызывать REST API. Один набор инструментов и одинаковые учетные данные для обеих версий.		Модели Gemini в Gemini API, Google AI Studio и Gemini Enterprise Agent Platform
Что возвращают инструменты	Основные факты: информация о местах (до пяти мест на поиск), расстояние и продолжительность маршрута без учета трафика в реальном времени, текущая погода и прогнозы (плюс почасовая история погоды за 24 часа), а также текущее или прогнозируемое качество воздуха.	Все возможности Essentials, а также места вдоль маршрута с указанием времени и расстояния объезда, расширенная информация о местах (например, данные из отзывов), до 10 мест на поиск, маршруты с учетом загруженности дорог в реальном времени, до 25 промежуточных путевых точек, прогнозы концентрации пыльцы и данные о качестве воздуха за последние 30 дней.	Информация о местах и отзывы о них, а также сведения о маршрутах с учетом загруженности дорог.
Примеры запросов	Фактические и логистические вопросы: поиск магазинов или компаний, часы работы, адреса, расстояние или расчетное время в пути, текущая погода, прогноз погоды на 10 дней, а также текущее качество воздуха или прогноз качества воздуха на 4 дня.	Субъективные, общие или специализированные вопросы: места вдоль маршрута, атмосфера, фирменные блюда, советы для посетителей, сравнение 6–10 мест, время в пути с учетом текущей загруженности дорог, прогнозы по пыльце и аллергии, а также история качества воздуха за последние 30 дней.	Поиск в режиме диалога, планирование маршрутов и поиск мест поблизости в Gemini
Визуализации Places UI Kit	Входит в стоимость токена визуализации данных агента (предварительная версия)		Оплачивается отдельно
Ежемесячный лимит бесплатного использования	10 000 запросов	5000 запросов	Зависит от платформы и модели. Например, в Gemini API для Gemini 3 и более новых моделей доступно 5000 бесплатных поисковых запросов в месяц. После этого цена за 1000 поисковых запросов составит 14 долларов США.
Цена при оплате по мере использования	7 долларов США за 1000 запросов, со скидками за объем	14 долларов США за 1000 запросов со скидками за объем
Подпишитесь, чтобы сэкономить	Входит в тарифные планы Essentials и Pro	Входит в тарифный план Pro	Недоступно
Начать	Одна настройка для обоих SKU: см. Как настроить LLM для использования MCP-сервера или Как вызывать инструменты с помощью REST.		Gemini API или Agent Platform

Эти параметры работают одинаково с обоими кодами: способы передвижения, время отправления и прибытия, альтернативные маршруты, ломаные линии маршрутов, поиск погоды, поиск текущего и прогнозируемого качества воздуха (включая концентрацию загрязняющих веществ и местные шкалы ИКВ), системы единиц измерения погоды и Resolution API. Они не влияют на то, по какому SKU оплачивается запрос.

Что оплачивается по тарифу Pro

В таблице ниже указано, какие возможности включены в Essentials, а какие требуют SKU Pro.

Инструмент	Возможности	Essentials	Pro
Поиск мест	Мест на запрос	До 5	6–10 (`page_size` из 6–10)
Поиск мест	Расширенная информация о местах в сводках поиска (выводы из отзывов, основные блюда в меню, атмосфера, загруженность, советы посетителей, а также расстояние или время в пути для запросов о близости).	Недоступно	Доступно в тарифном плане `include_extended_details`
Поиск на маршруте	Места вдоль маршрута, расстояние и время в пути при объезде, а также дополнительные сведения о местах или время объезда с учетом трафика.	Недоступно	Каждый запрос
Расчет маршрутов	Настройки маршрутизации	Не учитывает загруженность дорог в реальном времени.	Учитывает текущую загруженность дорог или данные об общественном транспорте в реальном времени, если используется `ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL`.
Расчет маршрутов	Промежуточные путевые точки на маршруте	До 10	От 11 до 25 (более 10 `intermediate_waypoints`)
Прогноз погоды	Погода	Текущая погода, почасовые и ежедневные прогнозы (до 10 дней) и почасовая история за последние 24 часа (`WEATHER` в `capabilities` или устаревшие запросы, в которых опущены `capabilities`, `weather_options`, `air_quality_options` и `language_code`).	Нет версий Pro (все данные `WEATHER` включены в Essentials)
	Качество воздуха	Текущие условия, почасовые результаты за весь день и почасовые прогнозы на срок до четырех дней (`AIR_QUALITY` в `capabilities`).	Исторические данные о качестве воздуха за последние 30 дней (`AIR_QUALITY` в `capabilities` с `date` до сегодняшнего дня или прошедшим `hour` в часовом поясе местоположения), если они возвращаются в ответе.
	Пыльца	Недоступно	Ежедневные прогнозы уровня пыльцы на срок до пяти дней и сведения о видах растений (`POLLEN` в `capabilities`), если они возвращаются в ответе.
Resolution API	Нет версий Pro. Все запросы оплачиваются по коду Places API Text Search Essentials (IDs Only) бесплатно.

Параметры запросов, которые включают каждую функцию, описаны в разделах Поиск мест, Поиск вдоль маршрута, Расчет маршрутов и Поиск погоды.

Как управлять использованием Pro

На устройствах search_places, compute_routes и lookup_weather профессиональные настройки по умолчанию отключены. LLM устанавливает их или вызывает search_along_route, когда этого требует запрос пользователя и позволяет описание инструмента или ваши инструкции. В описаниях инструментов указано, какие варианты стоят дороже и когда их использовать: page_size больше 5, расширенная информация о местах, более 10 промежуточных путевых точек, маршрутизация с учетом трафика и search_along_route. Если вы вызываете инструменты с помощью REST, ваш код задает все параметры. Чтобы управлять расходами:

Укажите, когда следует использовать Pro-версии. Например: "Задавай значение include_extended_details, только когда пользователь спрашивает об отзывах, меню или атмосфере". Или: "Используйте ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, только когда пользователь спрашивает о текущем времени в пути". Или: "Вызывай search_along_route, только когда пользователь спрашивает о местах на маршруте". Или: "Включай POLLEN или AIR_QUALITY с прошлым date или hour, только когда пользователь спрашивает о пыльце, аллергиях или качестве воздуха в прошлом".
Чтобы агент оставался на Essentials SKU, укажите в инструкции для модели, что она не должна вызывать search_along_route или использовать Pro-функции. К ним относятся: include_extended_details, page_size больше 5, ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, более 10 промежуточных путевых точек, POLLEN в capabilities, а также прошедшее время date или hour с AIR_QUALITY в capabilities. Если ваш клиент MCP может ограничивать инструменты или их аргументы, вы также можете заблокировать search_along_route и значения этих аргументов в конфигурации инструмента.
Отслеживайте SKU Maps Grounding Pro в отчетах об оплате и настройте оповещения о бюджете.

Resolution API

Инструменты агентов Maps Experience предоставляют Resolution API. Он преобразует текст и URL местоположений в свободной форме в структурированные идентификаторы мест Google Карт. Resolution API доступен в виде методов REST и инструментов на сервере MCP:

Resolve names (REST, MCP). Сопоставляет пакет названий или адресов с определенными местами на Google Картах. Этот инструмент помогает преобразовывать неструктурированные запросы пользователей в стабильные идентификаторы мест.
Resolve Maps URLs (REST, MCP) – сопоставляет набор URL Google Карт с определенными объектами мест. Поддерживаются стандартные и сокращенные URL.

Полученные идентификаторы мест можно использовать с другими API платформы Google Карт. Каждый ответ также содержит ссылку, по которой можно сохранить распознанные места в виде списка в Google Картах.

Подробную информацию вы найдете в статье Maps Tools Resolution API.

Попробуйте пример приложения (откроется в новой вкладке)

Оплата и квоты

Как взимается оплата

При использовании модели оплаты по мере использования платформы Google Карт использование инструментов агентов Maps Experience рассчитывается для каждого запроса. Каждый запрос представляет собой одно событие оплаты. Использование отслеживается отдельно для каждого кода продукта. В счете вы увидите строку для каждого SKU и общую сумму платежа. Подробнее об отчетах…

Каждый запрос на поиск мест, поиск по маршруту, расчет маршрутов или получение данных о погоде, отправленный через сервер MCP или REST, оплачивается по одному коду SKU: Maps Grounding Essentials или Maps Grounding Pro. Каждый запрос search_along_route и любой запрос, в котором используется функция Pro, оплачивается по тарифу Pro. Запрос никогда не оплачивается по обоим SKU, а количество параметров Pro в запросе не влияет на стоимость. Чтобы узнать, какие возможности и настройки определяют SKU для каждого инструмента, ознакомьтесь с разделом Что оплачивается по SKU Pro.

Запросы Maps Grounding Essentials оплачиваются по тарифу 7 долларов США за 1000 запросов после первых 10 000 запросов в месяц. Запросы Maps Grounding Pro оплачиваются по тарифу 14 долларов США за 1000 запросов после первых 5000 запросов в месяц. Для обеих версий предусмотрены скидки за объем при более высоком ежемесячном использовании.

Подробные сведения о ценах приведены в основной таблице цен и таблице цен для Индии.

Запросы к Resolution API (ResolveNames и ResolveMapsUrls) не оплачиваются. Они относятся к коду Places API Text Search Essentials (IDs Only).

Если вы показываете места из ответа search_places или search_along_route с помощью Places UI Kit, то можете использовать токен визуализации данных агента (предварительная версия), чтобы за запросы Places UI Kit не взималась плата.

Использование SKU Essentials включено в планы Essentials и Pro Подписка со скидкой. Использование SKU Pro включено в план Pro.

Квоты

Для инструментов и API, предоставляемых инструментами агентов Maps Experience, действуют следующие квоты:

Поиск мест. 300 запросов в минуту на проект.
Поиск по маршруту: 300 запросов в минуту на проект.
Поиск погоды: 300 запросов в минуту на проект.
Compute Routes: 300 запросов в минуту на проект.
Resolve names: 600 запросов в минуту на проект.
Resolve Maps URLs: 600 запросов в минуту на проект.

Квоты рассчитываются для каждого инструмента и являются общими для версий Essentials и Pro. Запрос Pro расходует ту же квоту, что и запрос Essentials к тому же инструменту.

Каждый запрос к Resolution API считается за один запрос, независимо от того, сколько элементов он содержит.

Правила и условия использования

На инструменты агентов Maps Experience распространяются Условия использования платформы Google Карт, включая Специальные условия использования. В этом разделе описаны дополнительные требования к использованию инструментов агента Maps Experience, включая совместимые LLM и атрибуцию источников. Требования применяются ко всем результатам, независимо от того, по какому коду оплачивается запрос.

Требования к совместимым LLM

Инструменты агентов Maps Experience можно использовать только с LLM, соответствующей Условиям использования платформы Google Карт.

Например, вы должны убедиться, что Контент Google Карт не кешируется, не хранится и не используется для улучшения выбранной вами LLM. Прежде чем использовать инструменты агентов Maps Experience, ознакомьтесь с Условиями использования для каждой модели, которую вы планируете использовать с этими инструментами. Запрещается использовать инструменты агента Maps Experience с моделями, которые используют входные данные для обучения или улучшения. Вы несете ответственность за то, чтобы использование модели полностью соответствовало ограничениям в отношении контента Google Карт, указанным в Условиях использования платформы Google Карт, включая условия для отдельных сервисов.

Требования к указанию авторства для источников Google Карт

Каждый ответ инструментов агентов Maps Experience содержит источники. При показе результатов, полученных с помощью инструментов агентов Maps Experience, вы должны указывать связанные источники Google Карт и соблюдать следующие требования:

Источники Google Карт должны быть указаны сразу после сгенерированного контента, который они подтверждают. Такой сгенерированный контент также называется обоснованными выходными данными.
Источники Google Карт должны быть видны в рамках одного взаимодействия с пользователем.

Источники для инструментов "Поиск мест" и "Поиск по маршруту"

Поля places инструмента search_places и results[].place инструмента search_along_route содержат источники, подтверждающие summary. Для каждого места возвращаются следующие метаданные:

place (название ресурса)
id
location
googleMapsLinks
attribution

Для каждого места необходимо создать предварительный просмотр ссылки, который соответствует следующим требованиям:

Укажите Google Карты в качестве источника, следуя рекомендациям по указанию авторства в текстовых ответах инструментов агентов Maps Experience.
Укажите ссылку на источник, используя googleMapsLinks.placeUrl из ответа.

Эти требования также распространяются на сводки, которые включают расширенные сведения о местах из Pro, например информацию из отзывов. В массиве summary каждое место обозначается индексом, начинающимся с нуля, например [0], который сопоставляется с записью в массиве places или results. Каждое место также включает googleMapsLinks.reviewsUrl, которое ссылается на отзывы о месте в Google Картах. Пользователи могут перейти по ней, чтобы посмотреть отзывы, на основе которых была создана статистика.

Голосовые интерфейсы

Если ваше приложение озвучивает результаты, полученные от инструментов агентов Maps Experience, вы также должны соблюдать требования к голосовым интерфейсам. Сводные указания:

Источники. Показывайте источники Google Карт в сопутствующем интерфейсе, который содержит дословную запись голосового разговора.
Активное раскрытие информации. В момент взаимодействия сообщайте пользователям, что контент, созданный ИИ, может включать информацию из Google Карт. Также сообщите, что подробные источники доступны в интерфейсе Companion. Это можно сделать на экране или с помощью голосовой команды.
Постоянное раскрытие информации. Добавьте постоянное пояснение, например в меню настроек голоса, о том, что контент, созданный ИИ, может включать контент Google Карт.
Запросы пользователей. Точно отвечайте на вопросы пользователей об источнике контента и направляйте их в сопутствующий интерфейс за подробностями.

Настройте LLM для использования MCP-сервера

Чтобы использовать инструменты агентов Maps Experience, вам нужен проект Google Cloud с включенным сервисом Maps Experience agent tools API. Кроме того, вам потребуется ключ API или идентификатор клиента OAuth. Затем вы можете настроить доступ LLM к MCP-серверу. Сервер MCP использует транспорт Streamable HTTP.

Включите инструменты агентов Maps Experience в облачном проекте Google Cloud.

Чтобы включить API в проекте, выполните следующие действия:

В консоли Google Cloud выберите проект, который хотите использовать для инструментов агентов Maps Experience.
Включите оплату для проекта в Google Cloud Console.
Включите инструменты агентов Maps Experience в библиотеке API Google Cloud Console.

Аутентификация с помощью ключа API

Вы можете использовать существующий ключ API с инструментами агентов Maps Experience или создать новый. В любом случае включите сервис API инструментов агентов Maps Experience как в проекте Google Cloud, так и в ключе.

Чтобы выполнить аутентификацию с помощью ключа API, сделайте следующее:

Создайте или настройте ключ API, следуя инструкциям в статье Начало работы с платформой Google Карт.
Передайте ключ MCP-серверу, используя заголовок X-Goog-Api-Key. Его нужно указать в качестве специального HTTP-заголовка в конфигурации инструмента MCP для LLM.

Аутентификация с помощью OAuth

Чтобы выполнить аутентификацию с помощью OAuth, создайте учетные данные OAuth и передайте их хосту MCP или приложению MCP-сервера.

Чтобы выполнить аутентификацию с помощью OAuth:

В консоли Google Cloud выберите проект, который хотите использовать для инструментов агентов Maps Experience.
В меню API & Services (API и сервисы) выберите Credentials (Учетные данные).
В верхнем меню выберите Создать учетные данные > Идентификатор клиента OAuth.
Если в проекте не настроено окно запроса доступа, нажмите Настроить окно запроса доступа и следуйте инструкциям на экране.
В разделе Показатели нажмите Создать клиент OAuth.
На экране Create OAuth client ID (Создать идентификатор клиента OAuth) выберите тип приложения и введите название идентификатора клиента.
Укажите дополнительные сведения, относящиеся к типу вашего приложения. Например, если вы создаете веб-приложение, добавьте авторизованные URI для запросов браузера и сервера.
После создания клиента сохраните идентификатор клиента и секретный код.
При настройке хоста или приложения MCP-сервера передайте идентификатор клиента OAuth и секретный код. Также необходимо запросить следующую область действия: https://www.googleapis.com/auth/maps-platform.mapstools.

Подробнее о том, как использовать протокол OAuth 2.0 для доступа к API Google…

Как настроить LLM для доступа к MCP-серверу инструментов агентов Maps Experience

После того как вы включите сервис инструментов агентов Maps Experience и создадите учетные данные, вы сможете настроить LLM для доступа к MCP-серверу. Следуйте инструкциям по настройке MCP для вашей LLM и используйте URL сервера MCP: https://mapstools.googleapis.com/mcp.

Подробнее о том, как настроить MCP в ИИ-приложении…

Как настроить инструменты агентов Maps Experience с помощью Gemini CLI

В этом разделе приведен пример настройки сервера MCP для инструментов агента Maps Experience с помощью Gemini CLI. Подробнее о том, как использовать MCP-серверы с Gemini CLI…

После установки Gemini CLI выполните команду gemini mcp add, чтобы настроить сервер MCP:
```
gemini mcp add -s user -t http -H 'X-Goog-Api-Key: API_KEY' maps-experience-agent-tools-mcp https://mapstools.googleapis.com/mcp
```
Если настройка выполнена успешно, вы увидите подтверждение того, что сервер добавлен в пользовательские настройки.

Чтобы проверить, работает ли сервер, выполните команду /mcp list:

> /mcp list

Configured MCP servers:

maps-experience-agent-tools-mcp - Ready (6 tools)
Tools:
-   compute_routes
-   lookup_weather
-   resolve_maps_urls
-   resolve_names
-   search_along_route
-   search_places

Начните задавать вопросы о Картах с помощью CLI. Например, попробуйте сказать "Порекомендуй рестораны в Маунтин-Вью". Gemini вызовет инструмент search_places от вашего имени.

Как настроить инструменты агентов Maps Experience с помощью Agent Development Kit (ADK)

В этом разделе показано, как настроить сервер MCP с помощью Agent Development Kit (ADK) на Python, Java или TypeScript.

Python

Полную реализацию этого примера можно найти на GitHub в репозитории adk-samples.

Шаг 1. Определите агента с помощью `McpToolset` для инструментов агентов Maps Experience

Измените файл agent.py. Замените YOUR_GOOGLE_MAPS_API_KEY своим ключом API.

# ./adk_agent_samples/mcp_agent/agent.py
import os
from google.adk.agents.llm_agent import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

# Retrieve the API key from an environment variable or directly insert it.
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_API_KEY")
if not GOOGLE_MAPS_API_KEY:
    GOOGLE_MAPS_API_KEY = "YOUR_GOOGLE_MAPS_API_KEY_HERE"

if GOOGLE_MAPS_API_KEY == "YOUR_GOOGLE_MAPS_API_KEY_HERE":
    print("WARNING: GOOGLE_MAPS_API_KEY is not set.")

root_agent = Agent(
    model='gemini-flash-latest',
    name='travel_planner_agent',
    description='A helpful assistant for planning travel routes.',
    tools=[
        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"
                }
            )
        )
    ]
)

Шаг 2. Убедитесь, что `init.py` существует

Убедитесь, что в том же каталоге, где находится файл agent.py, есть файл __init__.py.

from . import agent

Шаг 3. Запустите `adk web` и начните работу

Задайте переменную среды.
Задайте ключ Google Maps API в качестве переменной среды в терминале:
```
export GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_GOOGLE_MAPS_API_KEY"
        
```
Запустите adk web.
Чтобы запустить веб-интерфейс ADK, выполните следующую команду:
```
adk web
        
```
В интерфейсе:
- Выберите сеть travel_planner_agent.
- Попробуйте такие запросы:
  - "Завтра я буду в Сан-Франциско. Какая сейчас погода?"
  - "Найди кофейни рядом с парком "Золотые ворота".
  - "Проложи маршрут от GooglePlex до аэропорта Сан-Франциско".

Java

Определите агент, который инициализирует McpToolset в Java. Если вы не используете переменную среды, замените YOUR_GOOGLE_MAPS_API_KEY_HERE на полученный ключ API.

package agents;

import com.google.adk.agents.LlmAgent;
import com.google.adk.runner.InMemoryRunner;
import com.google.adk.sessions.SessionKey;
import com.google.adk.tools.mcp.McpToolset;
import com.google.adk.tools.mcp.StreamableHttpServerParameters;
import com.google.genai.types.Content;
import com.google.genai.types.Part;
import java.util.HashMap;
import java.util.Map;

public class MapsAgentCreator {
    public static void main(String[] args) {
        String googleMapsApiKey = System.getenv("GOOGLE_MAPS_API_KEY");
        if (googleMapsApiKey == null || googleMapsApiKey.trim().isEmpty()) {
            googleMapsApiKey = "YOUR_GOOGLE_MAPS_API_KEY_HERE";
            if ("YOUR_GOOGLE_MAPS_API_KEY_HERE".equals(googleMapsApiKey)) {
                System.out.println("WARNING: GOOGLE_MAPS_API_KEY is not set.");
            }
        }

        Map<String, String> headers = new HashMap<>();
        headers.put("X-Goog-Api-Key", googleMapsApiKey);
        headers.put("Content-Type", "application/json");
        headers.put("Accept", "application/json, text/event-stream");

        StreamableHttpServerParameters serverParams =
                StreamableHttpServerParameters.builder("https://mapstools.googleapis.com/mcp")
                        .headers(headers)
                        .build();

        try (McpToolset toolset = new McpToolset(serverParams)) {
            LlmAgent agent = LlmAgent.builder()
                    .model("gemini-flash-latest")
                    .name("travel_planner_agent")
                    .description("A helpful assistant for planning travel routes.")
                    .tools(toolset)
                    .build();

            System.out.println("Agent created: " + agent.name());

            InMemoryRunner runner = new InMemoryRunner(agent);
            String userId = "maps-user-" + System.currentTimeMillis();
            String sessionId = "maps-session-" + System.currentTimeMillis();
            String promptText =
                    "Please give me directions to the nearest pharmacy to Madison Square Garden.";

            SessionKey sessionKey = runner.sessionService()
                    .createSession(runner.appName(), userId, null, sessionId)
                    .blockingGet()
                    .sessionKey();
            System.out.println("Session created: " + sessionId + " for user: " + userId);

            Content promptContent = Content.fromParts(Part.fromText(promptText));
            System.out.println("\nSending prompt: \"" + promptText + "\" to agent...\n");

            runner.runAsync(sessionKey, promptContent)
                    .blockingForEach(event -> {
                        System.out.println("Event received: " + event.toJson());
                    });
        } catch (Exception e) {
            System.err.println("An error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

TypeScript

Определите агент, который инициализирует MCPToolset в TypeScript:

import 'dotenv/config';
import {LlmAgent, MCPToolset} from "@google/adk";

const googleMapsApiKey = process.env.GOOGLE_MAPS_API_KEY;
if (!googleMapsApiKey) {
    console.warn("WARNING: GOOGLE_MAPS_API_KEY is not set.");
    throw new Error(
        'GOOGLE_MAPS_API_KEY is not provided, please run "export GOOGLE_MAPS_API_KEY=YOUR_ACTUAL_KEY" to add that.'
    );
}

export const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "travel_planner_agent",
    description: "A helpful assistant for planning travel.",
    tools: [
        new MCPToolset({
            type: "StreamableHTTPConnectionParams",
            url: "https://mapstools.googleapis.com/mcp",
            transportOptions: {
                requestInit: {
                    headers: {
                        "X-Goog-Api-Key": googleMapsApiKey,
                        "Content-Type": "application/json",
                        "Accept": "application/json, text/event-stream"
                    }
                }
            }
        })
    ],
});

Как вызывать инструменты с помощью REST

Каждый инструмент в Maps Experience agent tools также доступен как метод REST. Вызывайте методы REST напрямую, если хотите подключить инструменты к собственному агенту или приложению, например чтобы объявить собственные функции для модели, выбрать, какие параметры она может задавать, или установить значения по умолчанию в коде.

В таблице ниже перечислены методы REST для каждого инструмента.

Инструмент	Метод REST
`search_places`	`POST https://mapstools.googleapis.com/v1:searchText`
`search_along_route`	`POST https://mapstools.googleapis.com/v1:searchAlongRoute`
`lookup_weather`	`POST https://mapstools.googleapis.com/v1:lookupWeather`
`compute_routes`	`POST https://mapstools.googleapis.com/v1:computeRoutes`
`resolve_names`	`POST https://mapstools.googleapis.com/v1:resolveNames`
`resolve_maps_urls`	`POST https://mapstools.googleapis.com/v1:resolveMapsUrls`

REST-запрос принимает те же параметры, что и соответствующий инструмент, и возвращает тот же ответ. В телах запросов и ответов REST названия полей указываются в верблюжьем регистре, например textQuery вместо text_query. Запросы REST оплачиваются по тем же SKU, подчиняются тем же правилам для вариантов Pro и учитываются в тех же квотах, что и вызовы инструментов MCP.

Для аутентификации используйте тот же проект Google Cloud и учетные данные, что и для сервера MCP. Инструкции по настройке приведены в разделе Как настроить LLM для использования сервера MCP. Передайте ключ API в заголовке X-Goog-Api-Key или токен доступа OAuth с областью действия https://www.googleapis.com/auth/maps-platform.mapstools в заголовке Authorization.

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

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "textQuery": "coffee shops near Golden Gate Park"
}' \
"https://mapstools.googleapis.com/v1:searchText"

Укажите вместо API_KEY свой ключ API.

Ответ содержит те же поля summary, places и contentToken, что и результат инструмента search_places. В руководстве по каждому инструменту есть пример REST.

Отправка отзыва

Чтобы поделиться отзывом об инструментах агентов Maps Experience, используйте следующие формы: