Membangun Agen Analisis Google Trends dengan MCP BigQuery

1. Ringkasan

Dalam codelab ini, Anda akan membuat Agen Analisis Google Trends menggunakan Google ADK. Agen ini memanfaatkan server MCP BigQuery untuk menemukan dan menjalankan alat yang mengkueri set data publik Google Trends secara dinamis (bigquery-public-data.google_trends).

Yang akan Anda pelajari

Cara menyiapkan project untuk pengembangan ADK.
Cara mengaktifkan dan menggunakan server MCP Terkelola untuk BigQuery.
Cara membuat agen yang menggunakan alat MCP.
Cara menjalankan agen secara lokal untuk pengujian.
Cara men-deploy agen ke Google Cloud Run.

Yang Anda butuhkan

Project Google Cloud yang mengaktifkan penagihan
Browser web seperti Chrome
Python 3.11+

Codelab ini ditujukan bagi developer tingkat menengah yang sudah memahami Python dan Google Cloud.

Codelab ini membutuhkan waktu sekitar 15-20 menit untuk diselesaikan.

Resource yang dibuat dalam codelab ini seharusnya berbiaya kurang dari $5.

2. Menyiapkan lingkungan Anda

Membuat Project Google Cloud

Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Menetapkan Variabel Lingkungan

Tetapkan variabel lingkungan berikut.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_GENAI_USE_VERTEXAI=1

Catatan: Menetapkan GOOGLE_GENAI_USE_VERTEXAI=1 akan mengarahkan ADK untuk menggunakan Vertex AI, memanfaatkan Cloud IAM untuk autentikasi, bukan GEMINI_API_KEY.

Melakukan Autentikasi dan Mengonfigurasi gcloud

gcloud auth login
gcloud auth application-default login

Catatan: gcloud auth login mengautentikasi perintah gcloud CLI, sedangkan gcloud auth application-default login mengautentikasi kode aplikasi lokal.

Tetapkan project Google Cloud:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

Mengaktifkan API yang Diperlukan

Aktifkan Google Cloud API yang diperlukan untuk Cloud Run, Artifact Registry, BigQuery, dan Vertex AI.

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

Mengaktifkan MCP untuk BigQuery

Server MCP terkelola harus diaktifkan secara eksplisit untuk project Anda.

gcloud beta services mcp enable bigquery.googleapis.com

Membuat Folder Project

Mulai dengan membuat folder root untuk agen dan folder internal untuk penerapan agen.

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

3. Buat Kode Agen

Buat file kosong bernama google_trends/__init__.py:

touch google_trends/__init__.py

Kemudian, buat file bernama google_trends/agent.py dan tempelkan kode berikut:

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. Menjalankan agen

Pada langkah ini, Anda akan menyiapkan lingkungan virtual Python lokal, menginstal dependensi, dan menjalankan agen untuk memverifikasi perilakunya di komputer Anda (atau Google Cloud Shell).

Buka direktori root aplikasi (google-trends-agent).
Buat lingkungan virtual:

python -m venv mcp_demo_env
source mcp_demo_env/bin/activate

Instal paket Python yang diperlukan:

pip install google-auth google-adk

Kita akan menggunakan ADK Web untuk menguji agen baru.

Untuk pengembangan dan pengujian lokal, jalankan perintah berikut:

adk web

Untuk pengembangan dan pengujian dalam Google Cloud Shell, jalankan perintah berikut:

adk web --allow_origins="*"

Tindakan ini akan memulai server web ADK. Anda dapat berinteraksi dengan agen menggunakan antarmuka web lokal (biasanya di http://localhost:8000).

Catatan: Anda juga dapat menggunakan perintah adk run google_trends yang lebih sederhana untuk menguji agen.

5. Men-deploy ke Cloud Run

Ikuti langkah-langkah berikut untuk men-deploy agen secara aman ke Google Cloud Run.

Berikan Izin

Cloud Run memerlukan izin untuk mengakses Vertex AI dan menggunakan alat 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"

Buat Dockerfile

Di root project Anda (google-trends-agent), buat file bernama Dockerfile dan tempelkan konten berikut:

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

Men-deploy Agen

Jalankan perintah berikut dari direktori root. Tindakan ini akan membuat container dan men-deploy agen Anda ke Cloud Run.

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

Verifikasi Cepat

Setelah deployment selesai, konsol akan menampilkan URL Layanan. Buka URL ini di browser Anda; URL ini akan memberikan UI interaktif yang sama seperti yang Anda lihat secara lokal, tetapi kini berjalan di cloud.

Anda juga dapat memantau log untuk memastikan semuanya berjalan lancar:

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

6. Pembersihan

Untuk menghindari tagihan berkelanjutan, hapus resource yang dibuat selama codelab ini.

Hapus layanan Cloud Run:

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

Jika Anda membuat project khusus untuk codelab ini, Anda dapat menghapus seluruh project tersebut:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

Anda juga dapat menghapus semua file yang terkait dengan codelab ini:

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

7. Selamat

Selamat! Anda telah berhasil membuat dan men-deploy Agen Analisis Google Trends.