Эта страница переведена с помощью Cloud Translation API.

Создайте агента для планирования маршрутов с помощью ADK и Google Maps Grounding.

1. Введение

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

Что вы будете делать

Инициализируйте проект агента с помощью стартового пакета агента.
Настройте агента для использования инструмента Google Maps Grounding.
Протестируйте полученный агент локально с помощью веб-интерфейса.

Что вам понадобится

Веб-браузер, например Chrome.
Проект Google Cloud с включенной функцией выставления счетов.

Этот практический урок предназначен для разработчиков среднего уровня, которые знакомы с Python и Google Cloud, но не обязательно являются экспертами.

2. Прежде чем начать

Создайте проект в Google Cloud.

В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google 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. Установите стартовый пакет агента.

Самый простой способ начать проект ADK — это использовать Agent Starter Pack. Google Cloud Agent Starter Pack — это инструмент с открытым исходным кодом, представляющий собой интерфейс командной строки (CLI), разработанный для ускорения разработки и развертывания готовых к использованию агентов генеративного ИИ в Google Cloud.

Убедитесь, что uv установлен, затем выполните команду create для инициализации нового проекта агента:

uvx agent-starter-pack create

Если у вас не установлен uv , вы можете использовать pip :

# Create and activate a Python virtual environment
python -m venv .venv && source .venv/bin/activate

# Install the agent starter pack
pip install --upgrade agent-starter-pack

# Create a new agent project
agent-starter-pack create

Более подробную информацию можно найти в репозитории agent-starter-pack .

При появлении запроса укажите следующие параметры для настройки проекта для локальной разработки с использованием React-интерфейса:

Шаблон агента : adk (простой агент React)
Развертывание : none (развертывание в облаке временно отключено)
Регион : us-central1

В результате будет создана структура каталогов проекта, содержащая основную логику агента, тесты и руководство GEMINI.md . Перейдите в созданный каталог:

cd my-agent

4. Настройка заземления

Стартовый пакет агента генерирует файл GEMINI.md , содержащий инструкции для инструментов программирования с поддержкой ИИ по управлению вашим проектом. Мы обновим этот файл, чтобы включить в него документацию по приземлению в Google Maps.

Откройте GEMINI.md в вашем редакторе.
Добавьте следующую ссылку в раздел ## Reference Documentation :

- **Google Maps Grounding**: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps

Этот контекст поможет любым помощникам в программировании на основе ИИ понять принцип работы базовых функций.

5. Обновите данные агента.

Теперь мы настроим агента так, чтобы он действовал как планировщик маршрутов, используя инструмент Google Maps Grounding.

Откройте файл 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",
)

Этот код настраивает агент на базе gemini-2.5-flash , который использует инструмент google_maps_grounding для получения актуальной информации о местах и маршрутах.

Чтобы просмотреть все доступные модели, см. документацию Vertex AI .

6. Запустите агента

После того, как вы настроили логику работы агента, попробуйте протестировать её в локальном веб-интерфейсе.

В корневом каталоге вашего my-agent выполните следующую команду для запуска веб-приложения:

uv run adk web

или, если используется виртуальная среда:

adk web

Откройте в браузере URL-адрес, указанный в выводе терминала.
Проверьте работу агента, задав ему вопрос. Например:

«Составьте однодневный маршрут по Сан-Франциско, включающий посещение хорошего итальянского ресторана».
«Я собираюсь посетить Токио, не могли бы вы составить для меня маршрут с интересными историческими достопримечательностями и порекомендовать высококлассное место, где подают рамен и царит уютная атмосфера?»

В результате вы должны увидеть подробный маршрут, дополненный реальными отзывами и описаниями маршрутов, взятыми непосредственно из Google Maps.

Пример выходных данных маршрута агента

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. Извлечение закодированных полилиний

Помимо подтверждения факта заземления, вам может потребоваться извлечь определенные данные, такие как пути маршрута. Когда инструмент проверки заземления в Maps возвращает информацию о маршруте, он часто включает в себя «закодированную полилинию», которую можно использовать для отображения маршрута на карте.

Эту полилинию можно найти, проверив текст в атрибуте maps объекта grounding_chunks . Вот пример того, как её можно обнаружить:

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, удалите ресурсы, созданные в ходе этого практического занятия.

Если вы создали отдельный проект для этого практического занятия, удалите его полностью:

gcloud projects delete $PROJECT_ID

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

10. Поздравляем!

Поздравляем! Вы успешно создали агента для планирования маршрутов и настроили его с помощью аналитических данных Google Maps.

Что вы узнали

Как создать среду для нового агента с помощью стартового пакета агента.
Как добавить инструменты заземления в определение агента ADK
Как протестировать агент ADK с помощью встроенного веб-раннера

Следующие шаги

Изучите другие инструменты ADK и шаблоны интеграции.