Учим ai-агента ориентироваться на местности: кастомный tool на python и overpass (OSM)

Современные AI-агенты уже умеют планировать отпуск, писать код, и совершать покупки в интернете, но поставьте их перед простым вопросом «где лучше снять квартиру рядом с метро и школой» – и они начинают галлюцинировать. Они не понимают, что «5 минут до метро» и «500 метров по прямой через реку» – совершенно разные вещи. В результате пользователь получает красивые, но бесполезные советы.

Этим проектом я хочу показать, как дать агенту то, чего ему не хватает – «глаза» для карты. Как сделать так, чтобы агент понимал запрос «найди кафе рядом с парком», нашел реальные места в OpenStreetMap, посчитал, сколько идти пешком, и нарисовал всё на интерактивной карте. Никаких туманных рассуждений – только конкретика и работа координатами.

Кстати, еще больше экспериментов и заметок про AI-агентов – в моем Telegram: Maxim.ML ^[1]

Цель инструмента – решать прикладные запросы вроде:

• «Найди отели в Москве рядом с достопримечательностями».

• «Подбери районы Екатеринбурга с хорошей инфраструктурой (школы, транспорт, магазины)».

• «Где в Казани лучше открыть кофейню с учетом конкурентов и трафика?»

Зачем это нужно:

• Турист в незнакомом городе: вместо самостоятельного изучения карт просто спрашивает «покажи отели рядом с музеями» и получает готовую карту с рейтингом по доступности

• Предприниматель ищет место для кафе: за минуту видит, где много офисов и мало конкурентов, вместо долгих исследований.

• Семья переезжает: одним запросом находит районы, где есть и школа, и метро, и магазины в шаговой доступности.

Давайте посмотрим на то, как устроен этот tool для ai-агента

Архитектура и стек

Под капотом – три специализированных движка, каждый со своими особенностями:

1. Map Search Engine – высокоуровневый клиент к OpenStreetMap (Overpass API через overpy). Умеет:

   • парсить текстовый запрос в категории и область поиска;

   • отправлять один overpass-запрос по множеству OSM-тегов;

   • кэшировать ответы (pickle с TTL) и собирать метрики;

   • считать расстояния и матрицы расстояний/времени (по профилям car/foot/bicycle).

2. Map Visualization Engine – генерация интерактивных HTML-карт на Folium:

   • кластерные маркеры;

   • круги, полигоны, полилинии;

   • настраиваемая легенда.

3. Agent Engine – «мозг» для разбора естественных запросов на русском языке через локальный ollama:

   • извлекает локацию, типы POI, параметры визуализации;

   • дергает поиск и визуализацию;

   • формирует короткий аналитический отчет и метрики.

Важно: в текущей версии нет прокладки реальных маршрутов по графу дорог (osmnx) и нет пересечений буферов на GeoPandas. Все расстояния – геодезические с разумной аппроксимацией времени.

Немного про использование поисковых инструментов агентами

Современные AI-агенты работают с инструментами по принципу “сначала подумай, потом вызови”. В отличие от простых вызовов функций, агент должен самостоятельно понять, какие параметры нужны для search tool и как их получить из запроса пользователя.

Ключевое отличие от классического программирования: вместо жестко прописанных function(location, radius, poi_types) агент сам определяет, что location = “Екатеринбург”, radius = 1500, а poi_types = [“schools”, “metro_stations”, “shops”] из фразы “подбери район в Екатеринбурге с школами, метро и магазинами рядом”.

Основной принцип: агент получает четкую документацию инструмента с описанием доступных параметров и их типов, а затем самостоятельно извлекает нужные значения из контекста диалога или прямого запроса пользователя. Это делает систему гибкой – агент может работать с разными типами поисковых запросов без переписывания кода.

Самый надежный способ обеспечить правильное формирование параметров – использование structured output. Агент возвращает JSON с точно определенными полями:

{
  "location": "Екатеринбург",
  "search_radius": 1500,
  "poi_types": ["schools", "metro_stations", "shops"],
  "visualization_params": {
    "cluster_markers": true,
    "show_search_area": true,
    "legend_position": "bottomright"
  }
}

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

Качество карт очень сильно влияет на ответы агента

OpenStreetMap – это Wikipedia географического мира. В Москве данные отличные, в областном центре – по тегам на карте бывает пусто. И от этого напрямую зависит, насколько умным покажется ваш агент.

Представьте ситуации:

• Хорошие данные: «Найди кафе у Парка Горького» → 35 заведений с названиями, типами кухни и адресами. Агент построит красивую карту и даст внятные рекомендации.

• Скудные данные: «Найди кафе в <любой малый город>» → 2 безымянные точки без деталей. Результат разочарует пользователя.

Секрет в тегах OSM: чем больше amenity=restaurant, cuisine=italian, name=Кафе, тем точнее классификация и «важность» места. А значит – умнее рекомендации.

Практический вывод: этот tool будет расти вместе с данными. Подключите Google Maps или 2GIS – и тот же код выдаст результаты более качественного уровня.

Кейс-пример: «найди в Екатеринбурге учебные заведения радиусе 1.5 км от центра города, недалеко от парков для прогулок»

Семья ищет место в Екатеринбурге для обучения ^[2] ребенка. Требования простые: хороший район с парками.

Что делает текущая версия агента с map search tool:

• ищет категории schools, parks в пределах заданного радиуса по городу;

• вычисляет геодезические расстояния между группами точек и формирует простые рекомендации;

• визуализирует слои маркеров и область поиска на одной карте.

Другие кейсы применения map search tool в ваших ai агентах

1. Анализ конкурентной среды для бизнеса

Ресторатор хочет открыть новое заведение в Санкт-Петербурге. Агент анализирует плотность существующих ресторанов, близость к офисным центрам и транспортным узлам, выдавая тепловую карту “идеальных” локаций с минимальной конкуренцией и максимальным трафиком.

2. Оптимизация логистики доставки

Служба доставки ищет оптимальные места для размещения складов. Агент анализирует расположение клиентов, транспортную доступность, наличие парковок и близость к основным магистралям, предлагая точки с минимальным радиусом обслуживания.

3. Туристические рекомендации

Туристическое агентство создает индивидуальные маршруты. Агент учитывает интересы клиента (музеи, парки, рестораны), строит оптимальный маршрут с учетом расстояний между точками и времени посещения, создавая интерактивную карту путешествия.

4. Городское планирование и развитие

Муниципальные власти анализируют обеспеченность районов социальной инфраструктурой. Агент выявляет “пустые зоны” где не хватает школ, поликлиник или парков, помогая принимать решения о новом строительстве.

5. Риелторские услуги и подбор недвижимости

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

Куда развивать дальше

Текущий proof of concept уже неплохо работает. Но потенциал развития огромен:

• Реальные маршруты: не «500 метров по прямой», а «7 минут пешком с учетом светофоров». Подключаем граф дорог из OSM и osmnx.

• Умные зоны: вместо кругов – реальные изохроны доступности. «10 минут на транспорте» станет видимой областью на карте.

• Heatmap: сетки H3, агрегация плотностей, визуализация «где много людей, но мало кафе».

• Живые данные: отзывы из 2GIS, расписания транспорта, цены аренды, события – всё, что влияет на полезность ответа для пользователя.

• Умный агент: научить модель не просто искать, а объяснять «почему именно здесь» с фактами и аргументами

Формула проста: лучше данные → умнее выводы → счастливее пользователи. Этот проект – стартовая точка для серьезных location-based AI-инструментов.

Код проекта – в репозитории ^[3]. Буду рад обратной связи и идеям новых кейсов применения и развития.

P.S. Еще больше экспериментов и заметок про AI-агентов – в моем Telegram: Maxim.ML ^[1]