Xây dựng một tác nhân phân tích Google Xu hướng bằng MCP BigQuery

1. Tổng quan

Trong lớp học lập trình này, bạn sẽ tạo Tác nhân phân tích Google Xu hướng bằng Google ADK. Tác nhân này tận dụng máy chủ BigQuery MCP để tự động phát hiện và thực thi các công cụ truy vấn tập dữ liệu công khai của Google Xu hướng (bigquery-public-data.google_trends).

Kiến thức bạn sẽ học được

  • Cách thiết lập dự án để phát triển ADK.
  • Cách bật và sử dụng máy chủ MCP được quản lý cho BigQuery.
  • Cách tạo tác nhân sử dụng các công cụ MCP.
  • Cách chạy tác nhân cục bộ để kiểm thử.
  • Cách triển khai tác nhân lên Google Cloud Run.

Bạn cần có

  • Một dự án trên Google Cloud đã bật tính năng thanh toán
  • Một trình duyệt web như Chrome
  • Python 3.11 trở lên

Lớp học lập trình này dành cho các nhà phát triển trung cấp đã quen thuộc với Python và Google Cloud.

Bạn sẽ mất khoảng 15 đến 20 phút để hoàn thành lớp học lập trình này.

Các tài nguyên được tạo trong lớp học lập trình này sẽ có chi phí dưới 5 USD.

2. Thiết lập môi trường

Tạo một dự án trên Google Cloud

  1. Trong Google Cloud Console, trên trang bộ chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
  2. Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem một dự án đã bật tính năng thanh toán hay chưa.

Đặt các biến môi trường

Đặt các biến môi trường sau.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Lưu ý: Việc đặt GOOGLE_GENAI_USE_VERTEXAI=1 sẽ hướng ADK sử dụng Vertex AI, tận dụng Cloud IAM để xác thực thay vì GEMINI_API_KEY.

Xác thực và định cấu hình gcloud

Đăng nhập vào Tài khoản Google, đặt dự án đang hoạt động và định cấu hình Thông tin xác thực mặc định của ứng dụng.

gcloud auth login
gcloud auth application-default login

Lưu ý: gcloud auth login xác thực các lệnh CLI gcloud, trong khi gcloud auth application-default login xác thực mã xử lý ứng dụng cục bộ.

Đặt dự án trên Google Cloud:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Bật các API cần thiết

Bật các API cần thiết của Google Cloud cho Cloud Run, Artifact Registry, BigQuery và Vertex AI.

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

Bật MCP cho BigQuery

Bạn phải bật rõ ràng các máy chủ MCP được quản lý cho dự án của mình.

gcloud beta services mcp enable bigquery.googleapis.com

Tạo thư mục dự án

Bắt đầu bằng cách tạo một thư mục gốc cho tác nhân và một thư mục nội bộ cho quá trình triển khai tác nhân.

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

3. Tạo mã tác nhân

Tạo một tệp trống có tên là google_trends/__init__.py:

touch google_trends/__init__.py

Sau đó, hãy tạo một tệp có tên là google_trends/agent.py rồi dán mã sau:

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. Chạy tác nhân

Trong bước này, bạn sẽ thiết lập một môi trường ảo Python cục bộ, cài đặt các phần phụ thuộc và chạy tác nhân để xác minh hành vi của tác nhân trên máy của bạn (hoặc Google Cloud Shell).

  • Chuyển đến thư mục gốc của ứng dụng (google-trends-agent).
  • Tạo môi trường ảo:
python -m venv mcp_demo_env
source mcp_demo_env/bin/activate
  • Cài đặt các gói Python cần thiết:
pip install google-auth google-adk

Chúng ta sẽ sử dụng ADK Web để kiểm thử tác nhân mới.

Để phát triển và kiểm thử cục bộ, hãy chạy lệnh sau:

adk web

Để phát triển và kiểm thử trong Google Cloud Shell, hãy chạy lệnh sau:

adk web --allow_origins="*"

Thao tác này sẽ khởi động máy chủ web ADK. Bạn có thể tương tác với tác nhân bằng giao diện web cục bộ (thường là tại http://localhost:8000).

Lưu ý: Bạn cũng có thể sử dụng lệnh adk run google_trends đơn giản hơn để kiểm thử tác nhân.

5. Triển khai lên Cloud Run

Hãy làm theo các bước sau để triển khai tác nhân một cách an toàn lên Google Cloud Run.

Cấp quyền

Cloud Run cần có quyền truy cập vào Vertex AI và sử dụng các công cụ 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"

Tạo Dockerfile

Trong thư mục gốc của dự án (google-trends-agent), hãy tạo một tệp có tên là Dockerfile rồi dán nội dung sau:

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"]

Triển khai tác nhân

Chạy lệnh sau từ thư mục gốc. Thao tác này sẽ tạo vùng chứa và triển khai tác nhân của bạn lên Cloud Run.

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

Xác minh nhanh

Sau khi quá trình triển khai hoàn tất, bảng điều khiển sẽ xuất ra một URL dịch vụ. Hãy mở URL này trong trình duyệt của bạn; URL này sẽ cung cấp cùng một giao diện người dùng tương tác mà bạn đã thấy cục bộ, nhưng hiện đang chạy trên đám mây!

Bạn cũng có thể theo dõi nhật ký để đảm bảo mọi thứ đang chạy trơn tru:

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

6. Dọn dẹp

Để tránh bị tính phí liên tục, hãy xoá các tài nguyên được tạo trong lớp học lập trình này.

Xoá dịch vụ Cloud Run:

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

Nếu bạn tạo một dự án dành riêng cho lớp học lập trình này, bạn có thể xoá toàn bộ dự án:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Bạn cũng có thể xoá tất cả các tệp liên quan đến lớp học lập trình này:

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

7. Xin chúc mừng

Xin chúc mừng! Bạn đã tạo và triển khai thành công một Tác nhân phân tích Google Xu hướng.

Kiến thức bạn học được

  • Cách sử dụng MCP để tự động mở rộng các chức năng của tác nhân
  • Cách tạo và phân phát các tác nhân LLM bằng Google ADK
  • Cách triển khai và mở rộng quy mô tác nhân trên Cloud Run

Các bước tiếp theo

  • Thử sửa đổi tác nhân để truy vấn các tập dữ liệu BigQuery khác
  • Thêm các công cụ MCP khác để mở rộng chức năng của tác nhân

Tài liệu tham khảo