Membangun dan Men-deploy Agen AI dengan server MCP Gemini dan BigQuery di Cloud Run

1. Pengantar

Yang akan Anda pelajari

Cloud Run adalah platform komputasi serverless yang terkelola sepenuhnya yang memungkinkan Anda menjalankan aplikasi dan layanan dalam container tanpa mengelola infrastruktur yang mendasarinya.

Agent Development Kit (ADK) adalah framework pengembangan agen open source yang memungkinkan Anda membangun, men-debug, dan men-deploy agen AI yang andal dalam skala perusahaan.

BigQuery adalah data warehouse perusahaan serverless yang terkelola sepenuhnya yang memungkinkan Anda menyimpan, membuat kueri, dan menganalisis set data besar.

Model Context Protocol (MCP) menstandardisasi cara model bahasa besar (LLM) dan aplikasi atau agen AI terhubung ke sumber data eksternal. Server MCP memungkinkan Anda menggunakan alat, resource, dan perintahnya untuk melakukan tindakan dan mendapatkan data terbaru dari layanan backend-nya. Server MCP BigQuery memberi agen AI Anda cara langsung dan aman untuk menganalisis data di BigQuery. Server MCP yang terkelola sepenuhnya ini menghilangkan overhead pengelolaan, sehingga Anda dapat berfokus pada pengembangan agen cerdas.

2. Penyiapan dan Persyaratan

Mulai dari menetapkan project default dan region Cloud Run:

# set the project
gcloud config set project YOUR_PROJECT_ID

Ganti YOUR_PROJECT_ID dengan Project ID Google Cloud Anda.

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

Ganti CLOUD-RUN-REGION dengan salah satu region yang didukung oleh Cloud Run.

Berikut adalah variabel lingkungan yang akan digunakan di seluruh codelab ini. Anda dapat menyimpannya dalam file lingkungan dan "membuat sumber" file tersebut. Pastikan untuk menetapkan nilai project ID Anda dengan benar dan secara opsional region.

# 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

Aktifkan API yang diperlukan untuk Codelab ini. Perubahan API mungkin memerlukan waktu 2-3 menit agar dapat diterapkan.

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

3. Membuat Agen Data menggunakan Agent Development Kit

Menulis kode agen

Dari Terminal Cloud Shell atau terminal lokal Anda, buat direktori root untuk aplikasi agentik Anda:

mkdir data_agent

Buka Cloud Shell Editor atau editor teks lain, lalu buat agent.py di direktori 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 juga memerlukan __init__.py dan requirements.txt untuk deployment:

  • __init__.py harus memiliki impor untuk agen.
  • Daftar dependensi Python requirements.txt: google-adk untuk Agent Development Kit, dan mcp untuk klien Model Context Protocol.

Perintah ini membantu Anda membuat __init__.py dan requirements.txt:

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

Struktur folder akhir akan terlihat seperti ini:

data_agent/
    __init__.py
    agent.py
    requirements.txt

Mencoba agen secara lokal

Agent Development Kit dilengkapi dengan alat CLI adk - antarmuka terminal interaktif untuk menguji agen Anda. Hal ini berguna untuk pengujian cepat, interaksi yang di-script, dan pipeline CI/CD. Salah satu fitur yang disediakan adalah adk web - Antarmuka Web ADK - cara sederhana untuk mengembangkan dan men-debug agen Anda secara interaktif. ADK Web tidak dimaksudkan untuk digunakan dalam deployment produksi, tetapi mempermudah Anda mencoba agen.

Perintah ini meluncurkan adk web yang memulai server web lokal di port 8080.

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

Setelah layanan dimulai, buka halaman Web ADK lokal: http://localhost:8080/.

Jika Anda menggunakan Google Cloud Shell, klik tombol Web Preview Pratinjau Web, lalu pilih item menu "Preview on port 8080".

Di UI Web ADK, tanyakan kepada agen tentang data yang dapat diaksesnya:

What data do you have?

Agen akan menggunakan alat BigQuery MCP untuk menjelajahi set data citibike. Tindakan ini akan memberi Anda ringkasan tabel dan kolom yang tersedia dalam set data Citibike.

4. Men-deploy agen ke Cloud Run

Perintah ini akan men-deploy agen ke Cloud Run menggunakan CLI ADK.

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

Mencoba agen

Kami menggunakan opsi --with_ui untuk deployment agen kami. Agen di-deploy dengan Antarmuka Web ADK.

  1. Buka URL agen di browser web. perintah adk deploy menampilkannya, dan Anda juga dapat mengambil URL dengan menjalankan perintah gcloud run services:
gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'
  1. Minta agen untuk mengolah data Citibike yang tersedia:
We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

Agen harus menjelajahi set data Citibike menggunakan server MCP BigQuery, menjalankan beberapa Kueri SQL, dan menampilkan daftar 3 stasiun citibike.

5. Selamat!

Selamat, Anda telah menyelesaikan codelab.

Sebaiknya tinjau dokumentasi Cloud Run.

Yang telah kita bahas

  • Cara membuat Agen AI dengan Agent Development Kit dan Gemini
  • Cara menghubungkan agen ke server MCP BigQuery.
  • Cara men-deploy agen ke Cloud Run.

6. Pembersihan

Agar tidak menimbulkan biaya pada akun Google Cloud Anda untuk resource yang digunakan dalam tutorial ini, Anda dapat menghapus project atau menghapus setiap resource.

Opsi 1: Menghapus Layanan

Menghapus Layanan Cloud Run

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

Opsi 2: Menghapus Project

Untuk menghapus seluruh project, buka Manage Resources, pilih project yang Anda buat di Langkah 2, lalu pilih Delete. Jika menghapus project, Anda harus mengubah project di Cloud SDK. Anda dapat melihat daftar semua project yang tersedia dengan menjalankan gcloud projects list. Jika ingin tetap menggunakan command line, Anda juga dapat menggunakan perintah ini:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}