สร้างและติดตั้งใช้งาน AI Agent ด้วย Gemini และเซิร์ฟเวอร์ MCP ของ BigQuery ใน Cloud Run

1. บทนำ

สิ่งที่คุณจะได้เรียนรู้

Cloud Run เป็นแพลตฟอร์มการประมวลผลแบบ Serverless ที่มีการจัดการอย่างเต็มรูปแบบ ซึ่งช่วยให้คุณเรียกใช้แอปพลิเคชันและบริการที่อยู่ในคอนเทนเนอร์ได้โดยไม่ต้องจัดการโครงสร้างพื้นฐาน

Agent Development Kit (ADK) เป็นเฟรมเวิร์กการพัฒนา Agent แบบโอเพนซอร์สที่ช่วยให้คุณสร้าง ดีบัก และติดตั้งใช้งาน AI Agent ที่เชื่อถือได้ในระดับองค์กร

BigQuery เป็นคลังข้อมูลสำหรับองค์กรแบบ Serverless ที่มีการจัดการครบวงจร ซึ่งช่วยให้คุณจัดเก็บ ค้นหา และวิเคราะห์ชุดข้อมูลขนาดใหญ่ได้

Model Context Protocol (MCP) กำหนดมาตรฐานวิธีที่โมเดลภาษาขนาดใหญ่ (LLM) และแอปพลิเคชันหรือ Agent AI เชื่อมต่อกับแหล่งข้อมูลภายนอก เซิร์ฟเวอร์ MCP ช่วยให้คุณใช้เครื่องมือ แหล่งข้อมูล และพรอมต์เพื่อดำเนินการและรับข้อมูลที่อัปเดตจากบริการแบ็กเอนด์ได้ เซิร์ฟเวอร์ BigQuery MCP ช่วยให้ AI Agent วิเคราะห์ข้อมูลใน BigQuery ได้โดยตรงและปลอดภัย เซิร์ฟเวอร์ MCP ที่มีการจัดการอย่างเต็มรูปแบบนี้ช่วยลดภาระในการจัดการ ทำให้คุณมุ่งเน้นไปที่การพัฒนา Agent อัจฉริยะได้

2. การตั้งค่าและข้อกำหนด

เริ่มต้นด้วยการตั้งค่าโปรเจ็กต์เริ่มต้นและภูมิภาค Cloud Run ดังนี้

# set the project
gcloud config set project YOUR_PROJECT_ID

แทนที่ YOUR_PROJECT_ID ด้วยรหัสโปรเจ็กต์ Google Cloud

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

แทนที่ CLOUD-RUN-REGION ด้วยหนึ่งใน ภูมิภาคที่ Cloud Run รองรับ

ต่อไปนี้คือตัวแปรสภาพแวดล้อมที่จะใช้ตลอด Codelab นี้ คุณสามารถบันทึกตัวแปรเหล่านี้ในไฟล์สภาพแวดล้อมและ "source" ตัวแปรเหล่านั้น ตรวจสอบว่าได้ตั้งค่ารหัสโปรเจ็กต์และภูมิภาค (ไม่บังคับ) อย่างถูกต้อง

# 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

เปิดใช้ API ที่จำเป็นสำหรับ Codelab นี้ การเปลี่ยนแปลง API อาจใช้เวลา 2-3 นาทีจึงจะมีผล

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

3. สร้าง Data Agent โดยใช้ Agent Development Kit

เขียนโค้ดของ Agent

จากเทอร์มินัล Cloud Shell หรือเทอร์มินัลในเครื่อง ให้สร้างไดเรกทอรีรากสำหรับแอป Agentic ดังนี้

mkdir data_agent

เปิด Cloud Shell Editor หรือเครื่องมือแก้ไขข้อความอื่น แล้วสร้าง agent.py ในไดเรกทอรี 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 ยังต้องใช้ __init__.py และ requirements.txt สำหรับการติดตั้งใช้งานด้วย

  • __init__.py ต้องมีการนำเข้าสำหรับ Agent
  • requirements.txt แสดงรายการทรัพยากร Dependency ของ Python ได้แก่ google-adk สำหรับ Agent Development Kit และ mcp สำหรับไคลเอ็นต์ Model Context Protocol

คำสั่งต่อไปนี้ช่วยให้คุณสร้าง __init__.py และ requirements.txt ได้

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

โครงสร้างโฟลเดอร์สุดท้ายควรมีลักษณะดังนี้

data_agent/
    __init__.py
    agent.py
    requirements.txt

ลองใช้ Agent ในเครื่อง

Agent Development Kit มาพร้อมกับเครื่องมือ adk CLI ซึ่งเป็นอินเทอร์เฟซเทอร์มินัลแบบโต้ตอบสำหรับการทดสอบ Agent เครื่องมือนี้มีประโยชน์สำหรับการทดสอบอย่างรวดเร็ว การโต้ตอบที่เขียนสคริปต์ไว้ และไปป์ไลน์ CI/CD ฟีเจอร์หนึ่งที่เครื่องมือนี้มีคือ adk web - อินเทอร์เฟซเว็บ ADK - วิธีง่ายๆ ในการพัฒนาและดีบัก Agent แบบโต้ตอบ ADK Web ไม่ได้มีไว้สำหรับการใช้งานในการติดตั้งใช้งานจริง แต่ช่วยให้ลองใช้ Agent ได้อย่างตรงไปตรงมา

คำสั่งนี้จะเปิดใช้ adk web ซึ่งจะเริ่มเว็บเซิร์ฟเวอร์ในเครื่องบนพอร์ต 8080

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

เมื่อบริการเริ่มต้นแล้ว ให้เปิดหน้าเว็บ ADK ในเครื่องที่ http://localhost:8080/

หากคุณใช้ Google Cloud Shell ให้คลิกปุ่มตัวอย่างเว็บ ตัวอย่างเว็บ แล้วเลือกรายการเมนู "แสดงตัวอย่างบนพอร์ต 8080"

ใน UI เว็บ ADK ให้ถาม Agent เกี่ยวกับข้อมูลที่ Agent มีสิทธิ์เข้าถึง

What data do you have?

Agent จะใช้เครื่องมือ BigQuery MCP เพื่อสำรวจชุดข้อมูล Citibike และจะให้ภาพรวมของตารางและฟิลด์ที่มีในชุดข้อมูล Citibike

4. ติดตั้งใช้งาน Agent ใน Cloud Run

คำสั่งนี้จะติดตั้งใช้งาน Agent ใน Cloud Run โดยใช้ 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}"

ลองใช้ Agent

เราใช้ตัวเลือก --with_ui สำหรับการติดตั้งใช้งาน Agent ซึ่งจะติดตั้งใช้งาน Agent ด้วย อินเทอร์เฟซเว็บ ADK

  1. เปิด URL ของ Agent ในเว็บเบราว์เซอร์ คำสั่ง adk deploy จะแสดง URL และคุณยังดึงข้อมูล URL ได้โดยเรียกใช้คำสั่ง gcloud run services ดังนี้
gcloud run services describe bq-data-agent \
  --project $GOOGLE_CLOUD_PROJECT \
  --region $GOOGLE_CLOUD_REGION \
  --format 'value(status.url)'
  1. ขอให้ Agent ให้เหตุผลเกี่ยวกับข้อมูล Citibike ที่มี
We have budget for 3 coffee trucks.
We want to find the best city bike stations to place our coffee trucks.

Agent ควรสำรวจชุดข้อมูล Citibike โดยใช้เซิร์ฟเวอร์ BigQuery MCP เรียกใช้การค้นหา SQL 2-3 รายการ และแสดงรายการสถานี Citibike 3 แห่ง

5. ยินดีด้วย

ขอแสดงความยินดีที่ทำ Codelab นี้เสร็จสมบูรณ์

เราขอแนะนำให้คุณอ่านเอกสารประกอบของ Cloud Run

สิ่งที่เราได้พูดถึงไปแล้ว

  • วิธีสร้าง AI Agent ด้วย Agent Development Kit และ Gemini
  • วิธีเชื่อมต่อ Agent กับเซิร์ฟเวอร์ BigQuery MCP
  • วิธีติดตั้งใช้งาน Agent ใน Cloud Run

6. ล้างข้อมูล

หากต้องการหลีกเลี่ยงการเรียกเก็บเงินจากบัญชี Google Cloud สำหรับทรัพยากรที่ใช้ในบทแนะนำนี้ คุณสามารถลบโปรเจ็กต์หรือลบทรัพยากรแต่ละรายการได้

ตัวเลือกที่ 1: ลบบริการ

ลบบริการ Cloud Run

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

ตัวเลือกที่ 2: ลบโปรเจ็กต์

หากต้องการลบโปรเจ็กต์ทั้งหมด ให้ไปที่ จัดการทรัพยากร เลือกโปรเจ็กต์ที่สร้างขึ้นในขั้นตอนที่ 2 แล้วเลือก "ลบ" หากลบโปรเจ็กต์ คุณจะต้องเปลี่ยนโปรเจ็กต์ใน Cloud SDK คุณสามารถดูรายการโปรเจ็กต์ทั้งหมดที่มีได้โดยเรียกใช้ gcloud projects list หากต้องการใช้บรรทัดคำสั่งต่อไป คุณสามารถใช้คำสั่งนี้ได้ด้วย

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}