Xây dựng và triển khai các tác nhân AI bằng Gemini và máy chủ BigQuery MCP trong Cloud Run

1. Giới thiệu

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

• Cách tạo một Tác nhân AI bằng Bộ công cụ phát triển tác nhân (ADK) với Gemini trong Nền tảng tác nhân.
• Cách cấp cho các Đặc vụ AI quyền truy cập vào dữ liệu có cấu trúc trong BigQuery bằng máy chủ BigQuery MCP.

Cloud Run là một nền tảng điện toán không máy chủ, được quản lý toàn diện, cho phép bạn chạy các ứng dụng và dịch vụ được triển khai bằng vùng chứa riêng mà không cần quản lý bất kỳ cơ sở hạ tầng cơ bản nào.

Bộ công cụ phát triển tác nhân (ADK) là một khung phát triển tác nhân nguồn mở, cho phép bạn tạo, gỡ lỗi và triển khai các tác nhân AI đáng tin cậy ở quy mô doanh nghiệp.

BigQuery là một kho dữ liệu doanh nghiệp không máy chủ, được quản lý hoàn toàn, cho phép bạn lưu trữ, truy vấn và phân tích các tập dữ liệu khổng lồ.

Giao thức ngữ cảnh mô hình (MCP) chuẩn hoá cách các mô hình ngôn ngữ lớn (LLM) và ứng dụng hoặc tác nhân AI kết nối với các nguồn dữ liệu bên ngoài. Máy chủ MCP cho phép bạn sử dụng các công cụ, tài nguyên và câu lệnh của máy chủ để thực hiện các hành động và nhận dữ liệu mới nhất từ dịch vụ phụ trợ của máy chủ. Máy chủ MCP của BigQuery cung cấp cho các tác nhân AI của bạn một cách trực tiếp và an toàn để phân tích dữ liệu trong BigQuery. Máy chủ MCP được quản lý hoàn toàn này giúp loại bỏ chi phí quản lý, cho phép bạn tập trung vào việc phát triển các tác nhân thông minh.

2. Thiết lập và yêu cầu

Bạn có thể thực thi toàn bộ phòng thí nghiệm này trên dòng lệnh. Bạn có thể sử dụng Cloud Shell (nhấp vào biểu tượng dấu nhắc ở trên cùng bên phải của bảng điều khiển) để khởi động môi trường.

Bắt đầu bằng cách thiết lập dự án mặc định và khu vực Cloud Run:

# set the project
gcloud config set project YOUR_PROJECT_ID

Thay thế YOUR_PROJECT_ID bằng mã dự án của bạn trên Google Cloud.

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

Thay thế CLOUD-RUN-REGION bằng một trong các khu vực được Cloud Run hỗ trợ.

Sau đây là các biến môi trường sẽ được dùng trong suốt lớp học lập trình này. Bạn có thể lưu các biến này trong một tệp môi trường và "source" tệp đó. Đảm bảo bạn đặt đúng giá trị của mã dự án và khu vực (không bắt buộc).

# 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

Lưu ý: Bạn nên lưu đoạn mã này dưới dạng tệp kịch bản và sử dụng lại trong tương lai, trong trường hợp phiên Cloud Shell được đặt lại. Lưu tệp này dưới dạng env.sh và chạy source env.sh để thiết lập các biến môi trường khi chạy các bước tiếp theo. Không cam kết env.sh với hệ thống kiểm soát phiên bản.

Bật các API cần thiết cho Lớp học lập trình này. Các thay đổi về API có thể mất từ 2 đến 3 phút mới có hiệu lực.

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

3. Tạo một Tác nhân dữ liệu bằng Bộ công cụ phát triển tác nhân

Viết mã của tác nhân

Trong Cloud Shell Terminal hoặc thiết bị đầu cuối cục bộ, hãy tạo một thư mục gốc cho ứng dụng dựa trên tác nhân của bạn:

mkdir data_agent

Mở Cloud Shell Editor hoặc một trình chỉnh sửa văn bản khác rồi tạo agent.py trong thư mục 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 cũng yêu cầu __init__.py và requirements.txt để triển khai:

• __init__.py phải có một lệnh nhập cho tác nhân.
• requirements.txt liệt kê các phần phụ thuộc Python: google-adk cho Agent Development Kit và mcp cho ứng dụng Giao thức ngữ cảnh mô hình.

Những lệnh này giúp bạn tạo __init__.py và requirements.txt:

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

Cấu trúc thư mục cuối cùng sẽ có dạng như sau:

data_agent/
    __init__.py
    agent.py
    requirements.txt

Dùng thử tác nhân cục bộ

Agent Development Kit đi kèm với công cụ adk CLI – một giao diện đầu cuối tương tác để kiểm thử các tác nhân của bạn. Điều này rất hữu ích cho việc kiểm thử nhanh, các hoạt động tương tác theo kịch bản và quy trình CI/CD. Một trong những tính năng mà công cụ này cung cấp là adk web – Giao diện web ADK – một cách đơn giản để phát triển và gỡ lỗi các tác nhân của bạn một cách tương tác. ADK Web không dành cho việc sử dụng trong các hoạt động triển khai sản xuất, nhưng giúp bạn dễ dàng dùng thử tác nhân.

Lưu ý: Trước khi chạy lệnh này, hãy đảm bảo thư mục hiện tại của bạn có thư mục data_agent (bằng lệnh ls).

Lệnh này sẽ khởi chạy adk web để khởi động một máy chủ web cục bộ trên cổng 8080.

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

Sau khi dịch vụ này khởi động, hãy mở trang web ADK cục bộ: http://localhost:8080/.

Nếu bạn đang sử dụng Google Cloud Shell, hãy nhấp vào nút Xem trước trên web rồi chọn mục "Xem trước trên cổng 8080".

Trong giao diện người dùng web ADK, hãy hỏi tác nhân về dữ liệu mà tác nhân có quyền truy cập:

What data do you have?

Tác nhân sẽ sử dụng các công cụ MCP của BigQuery để khám phá tập dữ liệu citibike. Thao tác này sẽ cung cấp cho bạn thông tin tổng quan về các bảng và trường có trong tập dữ liệu Citibike.

4. Triển khai tác nhân lên Cloud Run

Lệnh này sẽ triển khai tác nhân lên Cloud Run bằng 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 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}"

Dùng thử tác nhân

Chúng tôi đã sử dụng lựa chọn --with_ui để triển khai tác nhân. Nền tảng này đã triển khai tác nhân bằng Giao diện web ADK.

1. Mở URL của trợ lý ảo trong trình duyệt web. Lệnh adk deploy đã trả về URL này và bạn cũng có thể truy xuất URL bằng cách chạy lệnh gcloud run services:

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

2. Yêu cầu tác nhân suy luận dựa trên dữ liệu có sẵn của Citibike:

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

Nhân viên hỗ trợ nên khám phá tập dữ liệu Citibike bằng máy chủ BigQuery MCP, chạy một vài truy vấn SQL và trả về danh sách 3 trạm Citibike.

5. Xin chúc mừng!

Chúc mừng bạn đã hoàn thành lớp học lập trình này!

Bạn nên xem tài liệu về Cloud Run.

Nội dung đã đề cập

• Cách tạo một Tác nhân AI bằng Bộ công cụ phát triển tác nhân và Gemini
• Cách kết nối tác nhân với máy chủ MCP BigQuery.
• Cách triển khai tác nhân lên Cloud Run.

6. Dọn dẹp

Để không bị tính phí cho tài khoản Google Cloud đối với các tài nguyên được dùng trong hướng dẫn này, bạn có thể xoá dự án hoặc xoá từng tài nguyên.

Cách 1: Xoá dịch vụ

Xoá dịch vụ Cloud Run

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

Cách 2: Xoá dự án

Để xoá toàn bộ dự án, hãy chuyển đến phần Quản lý tài nguyên, chọn dự án bạn đã tạo ở Bước 2 rồi chọn Xoá. Nếu xoá dự án, bạn sẽ cần thay đổi dự án trong Cloud SDK. Bạn có thể xem danh sách tất cả các dự án có sẵn bằng cách chạy gcloud projects list. Nếu muốn sử dụng dòng lệnh, bạn cũng có thể dùng lệnh sau:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}