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

Создайте агент Google Trends Analyst с помощью BigQuery MCP.

1. Обзор

In this codelab, you will build a Google Trends Analyst Agent using the Google ADK . This agent leverages the BigQuery MCP server to dynamically discover and execute tools that query the Google Trends public dataset ( bigquery-public-data.google_trends ).

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

Как настроить проект для разработки на основе ADK.
Как включить и использовать управляемые MCP-серверы для BigQuery.
Как создать агента, использующего инструменты MCP.
Как запустить агент локально для тестирования.
Как развернуть агент в Google Cloud Run.

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

Проект Google Cloud с включенной функцией выставления счетов.
A web browser such as Chrome
Python 3.11+

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

Выполнение этого практического задания займет приблизительно 15-20 минут.

Стоимость ресурсов, созданных в рамках этого практического занятия, должна составлять менее 5 долларов.

2. Настройте свою среду.

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

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

Установка переменных среды

Установите следующие переменные среды.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Примечание : Установка параметра GOOGLE_GENAI_USE_VERTEXAI=1 указывает ADK использовать Vertex AI, задействуя Cloud IAM для аутентификации вместо GEMINI_API_KEY .

Аутентификация и настройка gcloud

Войдите в свой аккаунт Google, выберите активный проект и настройте учетные данные приложения по умолчанию.

gcloud auth login
gcloud auth application-default login

Примечание : gcloud auth login аутентифицирует команды CLI gcloud , а gcloud auth application-default login аутентифицирует локальный код приложения.

Настройте проект Google Cloud:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Включите необходимые API

Включите необходимые API Google Cloud для Cloud Run, Artifact Registry, BigQuery и Vertex AI.

gcloud services enable run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       bigquery.googleapis.com \
                       aiplatform.googleapis.com

Включить MCP для BigQuery

Для вашего проекта необходимо явно включить управляемые серверы MCP.

gcloud beta services mcp enable bigquery.googleapis.com

Создать папку проекта

Для начала создайте корневую папку для вашего агента и внутреннюю папку для реализации агента.

mkdir google-trends-agent
cd google-trends-agent
mkdir google_trends

3. Создайте код агента.

Создайте пустой файл с именем google_trends/__init__.py :

touch google_trends/__init__.py

Затем создайте файл с именем google_trends/agent.py и вставьте в него следующий код:

import os
import textwrap
import warnings
from datetime import date

import google.auth
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.auth.transport.requests import Request

# Suppress experimental ADK credential warnings
warnings.filterwarnings("ignore")

def get_agent_instruction(project_id: str) -> str:
    """Generates a clear and formatted prompt for the data analyst."""
    instruction = f"""
    # ROLE
    You are a Google Search Trends Analyst. Your mission is to provide clear answers using SQL data.

    # DATA CONSTRAINTS
    - BigQuery tool `execute_sql` requires explicit billing project mapping. Use: '{project_id}'.
    - Target dataset strictly: `bigquery-public-data.google_trends`

    # SCHEMA DISCOVERY (CRITICAL)
    1. DO NOT call `get_table_info` or `list_table_ids` (Triggers Permission Errors).
    2. Run `SELECT * FROM table LIMIT 0` via `execute_sql` for field definition mapping.

    # OUTPUT PRESENTATION
    - Render purely as a cleanly aligned Markdown table.
    - Use clear and descriptive headers for each column.
    - Remove conversational preambles. Output only the results.
    """
    return textwrap.dedent(instruction).strip()

def get_auth_headers() -> dict[str, str]:
    """Fetch auth headers for the project using Google Cloud Platform scopes."""
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/cloud-platform"]
    )
    request = Request()
    credentials.refresh(request)

    return {"Authorization": f"Bearer {credentials.token}"}

def get_todays_date() -> str:
    """Returns today's date in YYYY-MM-DD format."""
    return date.today().isoformat()

# --- Application Initialization ---
project_id = os.environ.get("GOOGLE_CLOUD_PROJECT")
if not project_id:
    raise ValueError("GOOGLE_CLOUD_PROJECT environment variable is not set")

mcp_headers = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
} | get_auth_headers()

# Configure BigQuery Tools via MCP
bq_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers=mcp_headers,
    )
)

# Initialize the LLM Agent
root_agent = LlmAgent(
    name="google_trends",
    model="gemini-3-flash-preview",
    tools=[get_todays_date, bq_tools],
    instruction=get_agent_instruction(project_id),
)

# Create the ADK App
app = App(name=root_agent.name, root_agent=root_agent)

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

На этом этапе вы настроите локальную виртуальную среду Python, установите зависимости и запустите агент, чтобы проверить его работу на вашем компьютере (или в Google Cloud Shell).

Перейдите в корневой каталог приложения ( google-trends-agent ).
Создайте виртуальную среду:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

Установите необходимые пакеты Python:

pip install google-auth google-adk

Для тестирования нашего нового агента мы будем использовать ADK Web .

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

adk web

Для разработки и тестирования в Google Cloud Shell выполните следующую команду:

adk web --allow_origins="*"

Это запустит веб-сервер ADK. Вы можете взаимодействовать с агентом через локальный веб-интерфейс (обычно по адресу http://localhost:8000 ).

Примечание : Для тестирования агента вы также можете использовать более простую команду adk run google_trends .

5. Развертывание в облаке

Выполните следующие шаги, чтобы безопасно развернуть агент в Google Cloud Run.

Предоставление разрешений

Для работы Cloud Run требуется разрешение на доступ к Vertex AI и использование инструментов BigQuery MCP.

# Get your project number automatically
PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format='value(projectNumber)')

# Vertex AI Access: To talk to the Gemini model
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/aiplatform.user"

# MCP & BigQuery: To execute tools and run SQL jobs
gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/mcp.toolUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

gcloud projects add-iam-policy-binding ${GOOGLE_CLOUD_PROJECT} \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/bigquery.dataViewer"

Создайте Dockerfile.

В корневой директории вашего проекта ( google-trends-agent ) создайте файл с именем Dockerfile и вставьте в него следующее содержимое:

FROM python:3.11-slim
WORKDIR /app

# Create a non-root user
RUN adduser --disabled-password --gecos "" myuser
USER myuser
ENV PATH="/home/myuser/.local/bin:$PATH"

# Copy the agent folder into the container
COPY --chown=myuser:myuser google_trends/ /app/agents/google_trends/

# Install the python packages
RUN pip install google-auth google-adk

# Set environment variables
ENV GOOGLE_GENAI_USE_VERTEXAI=1

# Expose port
EXPOSE 8080

# Run ADK web server
CMD ["adk", "web", "--port=8080", "--host=0.0.0.0", "/app/agents"]

Разверните агента

Выполните следующую команду из корневого каталога. Это создаст контейнер и развернет ваш агент в Cloud Run.

gcloud run deploy google-trends-agent \
  --source . \
  --region us-west1 \
  --allow-unauthenticated \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}"

Quick Verification

После завершения развертывания консоль выведет URL-адрес службы . Откройте этот URL-адрес в браузере; вы увидите тот же интерактивный интерфейс, что и локально, но теперь работающий в облаке!

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

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=google-trends-agent" --limit 10

6. Clean Up

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

Delete the Cloud Run service:

gcloud run services delete google-trends-agent --region us-west1

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

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

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

deactivate
cd ..
rm -rf google-trends-agent

7. Congratulations

Поздравляем! Вы успешно создали и развернули агента Google Trends Analyst.

Что вы узнали

Как использовать MCP для динамического расширения возможностей агента.
Как создавать и запускать агентов LLM с помощью Google ADK
How to deploy and scale agents on Cloud Run

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

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