Создавайте и развертывайте агентов ИИ с помощью Gemini и сервера BigQuery MCP в Cloud Run.

1. Введение

Что вы узнаете

• Как создать ИИ-агента с помощью Agent Development Kit (ADK) и Gemini в Agent Platform .
• Как предоставить агентам ИИ доступ к структурированным данным в BigQuery с помощью сервера BigQuery MCP .

Cloud Run — это полностью управляемая бессерверная вычислительная платформа, позволяющая запускать контейнеризированные приложения и сервисы без необходимости управления какой-либо базовой инфраструктурой.

Agent Development Kit (ADK) — это платформа для разработки агентов с открытым исходным кодом, которая позволяет создавать, отлаживать и развертывать надежные агенты искусственного интеллекта в масштабах предприятия.

BigQuery — это полностью управляемое, бессерверное корпоративное хранилище данных, позволяющее хранить, запрашивать и анализировать огромные массивы данных.

Протокол контекста модели (MCP) стандартизирует способы подключения больших языковых моделей (LLM) и приложений или агентов искусственного интеллекта к внешним источникам данных. Серверы MCP позволяют использовать их инструменты, ресурсы и подсказки для выполнения действий и получения обновленных данных из их бэкэнд-сервиса. Сервер BigQuery MCP предоставляет вашим агентам ИИ прямой и безопасный способ анализа данных в BigQuery. Этот полностью управляемый сервер MCP устраняет накладные расходы на управление, позволяя вам сосредоточиться на разработке интеллектуальных агентов.

2. Настройка и требования

Всю эту лабораторную работу можно выполнить из командной строки. Для запуска среды можно использовать Cloud Shell (щелкните значок приглашения в правом верхнем углу консоли).

Начните с настройки проекта по умолчанию и региона Cloud Run:

# set the project
gcloud config set project YOUR_PROJECT_ID

Замените YOUR_PROJECT_ID на идентификатор вашего проекта в Google Cloud.

# set Cloud Run region
gcloud config set run/region CLOUD-RUN-REGION

Замените CLOUD-RUN-REGION на один из регионов, поддерживаемых Cloud Run .

Ниже приведены переменные окружения, которые будут использоваться на протяжении всего этого практического занятия. Вы можете сохранить их в файле окружения и выполнить команду «source». Убедитесь, что вы правильно указали значение идентификатора вашего проекта и, при необходимости, региона.

# Cloud Project Id and Cloud Run region
export GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT:-$(gcloud config get-value project -q)}"
export GOOGLE_CLOUD_REGION="${GOOGLE_CLOUD_REGION:-$(CR_REGION=$(gcloud config get-value run/region -q 2>/dev/null); echo "${CR_REGION:-us-central1}")}"
# Gemini API in Agent Platform
export GOOGLE_GENAI_USE_ENTERPRISE="True" # Use Agent Platform
export GOOGLE_CLOUD_LOCATION="global" # Use global Gemini API endpoint

Примечание: Этот фрагмент кода полезно сохранить как скриптовый файл и использовать его повторно в будущем, например, при сбросе сессии Cloud Shell. Сохраните его как env.sh и запустите source env.sh , чтобы установить переменные окружения при выполнении последующих шагов. Не добавляйте файл env.sh в системы контроля версий.

Включите API, необходимые для этого практического занятия. Изменения в API могут вступить в силу через 2-3 минуты.

gcloud services enable --project "${GOOGLE_CLOUD_PROJECT}" \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    bigquery.googleapis.com \
    aiplatform.googleapis.com

3. Создайте агент данных с помощью Agent Development Kit.

Напишите код агента

Создайте корневой каталог для вашего приложения Agentic в терминале Cloud Shell или на локальном терминале:

mkdir data_agent

Откройте Cloud Shell Editor или другой текстовый редактор и создайте agent.py в каталоге data_agent :

data_agent/
    agent.py

agent.py

import os

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

import google.auth
from google.auth.transport.requests import Request

# Fetch Application Default Credentials (ADC)
# to use as agent's own identity for accessing BigQuery MCP Server
_application_default_credentials, project_id = google.auth.default()
_request = Request()
_application_default_credentials.refresh(_request)

# Retrieve Google Cloud project to use.
project_id = os.getenv("GOOGLE_CLOUD_PROJECT", project_id)
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set.")

# Builds authentication headers for MCP Server requests,
# and refreshes credentials if needed.
def _adc_auth_header_provider(context = None) -> dict[str, str]:
    if not _application_default_credentials.valid:
        _application_default_credentials.refresh(_request)

    return {
        "Authorization": f"Bearer {_application_default_credentials.token}",
        "x-goog-user-project": project_id
    }

# Initialize the MCP Toolset with the connection parameters
bigquery_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        tool_filter=[
            'get_dataset_info',
            'list_table_ids',
            'get_table_info',
            # Using readonly is a security measure to prevent accidental data modification.
            'execute_sql_readonly',
        ]
    ),
    header_provider=_adc_auth_header_provider # Auth header provider function
)

# Configure the agent

system_instruction = f"""
You are a helpful assistant that can answer questions about data in BigQuery.
To answer the user's question, use data you have access to by using tools `list_table_ids` and `get_table_info`.
Your data is in `bigquery-public-data.new_york_citibike` dataset (Citi Bike trips and stations in the NYC area.)

Plan of action:
0. ALWAYS start by analyzing dataset.
1. Analyze your data, investigate schema and dimensions by querying distrinct values of columns using `execute_sql_readonly`.
   Output information about tables, columns, their data types and sets of values (for dimensions).
   Note which columns can be joined or used in aggregations/filters, and what type conversion may be needed for joining or aggregating.
   DO NOT MAKE ASSUMPTIONS ABOUT DATA (structure, type, values, relationships) BASED ON YOUR PRIOR KNOWLEDGE. ALWAYS VERIFY YOUR ASSUMPTIONS.
2. Understand and interpret the user's question.
3. Formulate a plan to answer the user's question.
4. Write a SQL query to retrieve relevant data in necessary form.
   This is where you must pay extra attention to column types and dimensions' sets of values.
5. Retrieve data by generating BigQuery SQL and using `execute_sql_readonly`.
   Always use Dry Run to verify SQL correctness.
   Use `{project_id}` to run BigQuery queries (`project_id` parameter of `execute_sql_readonly`).

Do not use LaTeX in your responses. When giving a final answer, use Markdown.
"""

root_agent = LlmAgent(
    model="gemini-3.6-flash",
    name="data_agent",
    instruction=system_instruction,
    description="A helpful assistant that can answer questions using NYC Citibike data.",
    tools=[bigquery_toolset]
)

Для развертывания ADK также требуются __init__.py и requirements.txt :

• В файле __init__.py необходимо импортировать агента.
• В файле requirements.txt перечислены зависимости Python: google-adk для Agent Development Kit и mcp для клиента Model Context Protocol.

Эти команды помогут вам создать __init__.py и requirements.txt :

echo "from . import agent" > data_agent/__init__.py
echo -e "google-adk==2.4.*\nmcp==1.29.*" > data_agent/requirements.txt

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

data_agent/
    __init__.py
    agent.py
    requirements.txt

Попробуйте связаться с местным агентом.

В состав Agent Development Kit входит инструмент adk CLI — интерактивный терминальный интерфейс для тестирования ваших агентов. Это полезно для быстрого тестирования, скриптовых взаимодействий и конвейеров CI/CD. Одна из его функций — adk web — веб-интерфейс ADK — простой способ интерактивной разработки и отладки ваших агентов. ADK Web не предназначен для использования в производственных средах, но значительно упрощает тестирование агентов.

Примечание: Перед выполнением этой команды убедитесь, что в текущем каталоге находится каталог data_agent (с помощью команды ls ).

Эта команда запускает adk web , который создает локальный веб-сервер на порту 8080.

uv tool run --with "mcp==1.29.*" --from "google-adk[mcp]==2.4.*" adk web --allow_origins="*" --port 8080 .

После запуска службы откройте локальную веб-страницу ADK: http://localhost:8080/.

Если вы используете Google Cloud Shell , нажмите «Предварительный просмотр веб-страницы». нажмите кнопку и выберите пункт меню "Предварительный просмотр на порту 8080".

В веб-интерфейсе ADK запросите у агента информацию о данных, к которым у него есть доступ:

What data do you have?

Агент будет использовать инструменты BigQuery MCP для изучения набора данных Citibike. Он предоставит вам обзор доступных таблиц и полей в наборе данных Citibike.

4. Разверните агент в Cloud Run.

Эта команда развернет агент в Cloud Run с помощью ADK CLI.

uv tool run --from google-adk==2.4.0 \
  adk deploy cloud_run \
      --with_ui \
      --project $GOOGLE_CLOUD_PROJECT \
      --region $GOOGLE_CLOUD_REGION \
      --service_name bq-data-agent \
      --app_name data_agent \
      data_agent \
      -- \
      --allow-unauthenticated \
      --max-instances 1 \
      --labels dev-tutorial=codelab-cloud-run-adk-gemini-bq-mcp \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}

Попробуйте обратиться к агенту.

Для развертывания агента мы использовали опцию --with_ui . Она развернула агента с веб-интерфейсом ADK .

1. Откройте URL-адрес агента в веб-браузере. Команда adk deploy вернет его, а также вы можете получить URL-адрес, выполнив команду ` gcloud run services :

gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'

2. Попросите агента проанализировать имеющиеся данные о Citibike:

We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

Агент должен изучить набор данных Citibike с помощью сервера BigQuery MCP, выполнить несколько SQL-запросов и получить список из 3 станций Citibike.

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

Поздравляем с завершением практического занятия!

Мы рекомендуем ознакомиться с документацией Cloud Run .

Что мы рассмотрели

• Как создать ИИ-агента с помощью Agent Development Kit и Gemini
• Как подключить агент к серверу BigQuery MCP.
• Как развернуть агент в Cloud Run.

6. Уборка

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

Вариант 1: Удалить услугу

Удалите службу Cloud Run.

gcloud run services delete bq-data-agent \
      --project "${GOOGLE_CLOUD_PROJECT}" \
      --region "${GOOGLE_CLOUD_REGION}" \
      --quiet

Вариант 2: Удалить проект

Чтобы удалить весь проект, перейдите в раздел «Управление ресурсами» , выберите проект, созданный на шаге 2, и нажмите «Удалить». Если вы удалите проект, вам потребуется изменить проекты в вашем Cloud SDK. Вы можете просмотреть список всех доступных проектов, выполнив gcloud projects list . Если вы хотите использовать командную строку, вы также можете использовать следующую команду:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}