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

Создайте агент ADK для анализа местоположения с использованием серверов MCP для BigQuery и Google Maps.

1. Введение

В этом практическом занятии вы создадите агента с помощью ADK, работающего на платформе Gemini 3.0 Pro. Агент будет оснащен инструментами с двух удаленных (размещенных Google) серверов MCP для безопасного доступа к BigQuery для получения демографических данных, информации о ценах и продажах, а также к Google Maps для анализа и проверки местоположения в реальном мире.

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

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

Подготовка данных: Создайте базовый набор данных о пекарне в BigQuery.
Разработка агента: Создайте интеллектуального агента, используя комплект разработки агентов (ADK).
Интеграция инструментов: Обеспечьте агента функционалом BigQuery и Maps через сервер MCP.
Анализ рынка: Взаимодействуйте с агентом, чтобы оценить рыночные тенденции и степень насыщенности.

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

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

Этот практический семинар предназначен для разработчиков всех уровней, включая начинающих. Вы будете использовать интерфейс командной строки Google Cloud Shell и код Python для разработки ADK. Вам не обязательно быть экспертом в Python, но базовое понимание того, как читать код, поможет вам освоить основные концепции.

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

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

В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .

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

Запустить Cloud Shell

Cloud Shell — это среда командной строки, работающая в Google Cloud и поставляемая с предустановленными необходимыми инструментами.

В верхней части консоли Google Cloud нажмите кнопку «Активировать Cloud Shell» :

После подключения к Cloud Shell выполните следующую команду для проверки аутентификации в Cloud Shell:

gcloud auth list

Выполните следующую команду, чтобы убедиться, что ваш проект настроен для использования с gcloud:

gcloud config get project

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

export PROJECT_ID=$(gcloud config get project)

3. Получите код

Клонируйте репозиторий

Клонируйте репозиторий в свою среду Cloud Shell:

git clone https://github.com/google/mcp.git

Перейдите в каталог с демонстрационными версиями:

cd mcp/examples/launchmybakery

Аутентификация

Выполните следующую команду для аутентификации в вашей учетной записи Google Cloud. Это необходимо для доступа ADK к BigQuery.

gcloud auth application-default login

Следуйте инструкциям, чтобы завершить процесс аутентификации.

4. Настройка среды и BigQuery.

Запуск скриптов установки

Run the environment setup script. This script enables the BigQuery and Google Maps APIs, and creates a .env file with your Project ID and Maps API Key.

chmod +x setup/setup_env.sh
./setup/setup_env.sh

Запустите скрипт настройки BigQuery. Этот скрипт автоматизирует создание сегмента Cloud Storage, загрузку данных и подготовку набора данных и таблиц BigQuery.

chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

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

Демографические данные — данные переписи населения и характеристики населения по почтовым индексам.
bakery_prices - цены конкурентов и подробная информация о продукции на различные виды выпечки.
sales_history_weekly - еженедельные показатели продаж (количество и выручка) по магазинам и товарам.
foot_traffic - оценочные показатели пешеходного потока по почтовому индексу и времени суток.

Убедитесь, что набор данных и таблицы созданы, посетив консоль BigQuery в вашем проекте Google Cloud:

5. Установите ADK.

Теперь, когда инфраструктура готова, давайте создадим виртуальную среду Python и установим необходимые пакеты для ADK.

Создайте виртуальную среду:

python3 -m venv .venv

Активируйте виртуальную среду:

source .venv/bin/activate

Установите ADK:

pip install google-adk

Перейдите в каталог агентов:

cd adk_agent/

6. Проверьте приложение ADK.

Нажмите кнопку «Открыть редактор» в Cloud Shell, чтобы открыть редактор Cloud Shell и просмотреть клонированный репозиторий в каталоге mcp/examples/launchmybakery .

Код агента уже находится в каталоге adk_agent/ . Давайте рассмотрим структуру решения:

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

Ключевые файлы в mcp_bakery_app :

agent.py : Основная логика, определяющая агента, его инструменты и модель (Gemini 3.0 Pro Preview).
tools.py : Содержит определения пользовательских инструментов.
.env : Содержит конфигурацию вашего проекта и секреты (например, ключи API), созданные скриптом установки.

1. Инициализация набора инструментов MCP:

Теперь откройте adk_agent/mcp_bakery_app/tools.py в редакторе, чтобы понять, как инициализируются наборы инструментов MCP.

Для обеспечения возможности взаимодействия нашего агента с BigQuery и Google Maps необходимо настроить клиенты протокола контекста модели (MCP).

The code establishes secure connections to Google's remote MCP servers using StreamableHTTPConnectionParams .

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools

Инструментарий для работы с картами: Настраивает подключение к серверу Maps MCP с использованием вашего API-ключа.
Инструментарий BigQuery: Эта функция настраивает подключение к серверу BigQuery MCP. Она использует google.auth для автоматического получения ваших учетных данных Cloud, генерирует токен OAuth Bearer и внедряет его в заголовок Authorization.

2. Определение агента:

Теперь откройте adk_agent/mcp_bakery_app/agent.py в редакторе, чтобы посмотреть, как определен агент.

Инициализация LlmAgent осуществляется с использованием модели gemini-3-pro-preview .

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3-pro-preview',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)

Системные инструкции: Агенту даются конкретные указания по объединению данных из BigQuery (для анализа данных) и Maps (для анализа местоположения).
Инструменты: Агенту назначены наборы инструментов maps_toolset и bigquery_toolset , предоставляющие ему доступ к возможностям обоих сервисов.

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

7. Поговорите со своим агентом!

Вернитесь в терминал Cloud Shell и выполните эту команду, чтобы перейти в каталог adk_agent :

cd adk_agent

Выполните следующую команду, чтобы запустить веб-интерфейс ADK. Эта команда запускает легковесный веб-сервер для размещения приложения чата:

adk web

После запуска сервера вы можете пообщаться со своим агентом, перейдя по указанной ссылке, чтобы открыть веб-интерфейс ADK.

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

Найдите район (макроуровень): «Я хочу открыть пекарню в Лос-Анджелесе. Найдите почтовый индекс с самым высоким показателем пешеходного потока по утрам».

Агент должен использовать такие инструменты, как get_table_info и execute_sql для выполнения запросов к таблице foot_traffic в BigQuery.

Проверка местоположения (микропоиск): «Можете ли вы выполнить поиск по запросу „Пекарни“ в этом почтовом индексе, чтобы проверить, насколько он перенасыщен?»

The agent should use the search places tools in the Maps toolset to answer this question.

Попробуйте! Ознакомьтесь с этими примерами вопросов, чтобы увидеть работу вашего агента ADK:

«Я планирую открыть свою четвертую пекарню в Лос-Анджелесе. Мне нужен район с высокой активностью пешеходов в утренние часы. Найдите почтовый индекс с самым высоким показателем пешеходного потока по утрам».
«Можете поискать по этому почтовому индексу «пекарни», чтобы проверить, насколько много их в этом районе? Если их слишком много, проверьте наличие «кофейных заведений», чтобы я мог расположиться рядом с ними и привлечь больше посетителей».
«Хорошо, и я хочу позиционировать это как премиальный бренд. Какова максимальная цена, взимаемая за «буханку хлеба на закваске» в районе Лос-Анджелеса?»
«Теперь мне нужен прогноз выручки на декабрь 2025 года. Посмотрите на историю моих продаж и возьмите данные из моего самого успешного магазина по «Хлебу на закваске». Составьте прогноз на декабрь 2025 года, чтобы оценить количество проданного товара. Затем рассчитайте прогнозируемую общую выручку, используя цену чуть ниже той, которую мы нашли (возьмем, например, 18 долларов)».
«Этого хватит на оплату аренды. И наконец, давайте проверим логистику. Найдите ближайший к предполагаемому району склад "Restaurant Depot" и убедитесь, что время в пути для ежедневного пополнения запасов не превышает 30 минут».

8. Уборка

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

Запустите скрипт очистки. Этот скрипт удалит набор данных BigQuery, сегмент Cloud Storage и ключи API, созданные во время настройки.

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

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

Миссия выполнена! Вы успешно создали агента геолокационной аналитики, используя комплект разработки агентов (ADK).

Преодолев разрыв между вашими «корпоративными» данными в BigQuery и реальным контекстом местоположения из Google Maps , вы создали мощный инструмент, способный к сложным бизнес-рассуждениям — и все это благодаря протоколу контекста модели (MCP) и Gemini.

Чего вы достигли:

Инфраструктура как код: Вы создали стек данных с помощью инструментов командной строки Google Cloud.
Интеграция с MCP: Вы подключили агента ИИ к двум различным удаленным серверам MCP (BigQuery и Maps) без написания сложных API-оболочек.
Единое мышление: Вы создали единого агента, способного стратегически объединять знания из двух разных областей для решения бизнес-задачи.