Cloud Run में Gemini और BigQuery एमसीपी सर्वर की मदद से, एआई एजेंट बनाना और डिप्लॉय करना

1. परिचय

आपको क्या सीखने को मिलेगा

• Agent Platform में Gemini के साथ Agent Development Kit (ADK) का इस्तेमाल करके, एआई एजेंट बनाने का तरीका.
• BigQuery MCP सर्वर का इस्तेमाल करके, BigQuery में मौजूद स्ट्रक्चर्ड डेटा का ऐक्सेस एआई एजेंट को कैसे दिया जाता है.

Cloud Run, पूरी तरह से मैनेज किया गया, बिना सर्वर वाला कंप्यूट प्लैटफ़ॉर्म है. इसकी मदद से, कंटेनर वाले ऐप्लिकेशन और सेवाओं को चलाया जा सकता है. इसके लिए, आपको बुनियादी इंफ़्रास्ट्रक्चर को मैनेज करने की ज़रूरत नहीं होती.

Agent Development Kit (ADK), एजेंट डेवलपमेंट का एक ओपन-सोर्स फ़्रेमवर्क है. इसकी मदद से, एंटरप्राइज़ लेवल पर भरोसेमंद एआई एजेंट बनाए, डीबग किए, और डिप्लॉय किए जा सकते हैं.

BigQuery, पूरी तरह से मैनेज किया जाने वाला, बिना सर्वर वाला एंटरप्राइज़ डेटा वेयरहाउस है. इसकी मदद से, बड़े डेटासेट को स्टोर, क्वेरी, और उनका विश्लेषण किया जा सकता है.

मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी), यह तय करता है कि लार्ज लैंग्वेज मॉडल (एलएलएम) और एआई ऐप्लिकेशन या एजेंट, बाहरी डेटा सोर्स से कैसे कनेक्ट होंगे. एमसीपी सर्वर, आपको अपने टूल, संसाधन, और प्रॉम्प्ट इस्तेमाल करने की सुविधा देते हैं. इससे कार्रवाइयाँ की जा सकती हैं और बैकएंड सेवा से अपडेट किया गया डेटा पाया जा सकता है. BigQuery MCP Server, आपके एआई एजेंट को BigQuery में मौजूद डेटा का विश्लेषण करने का एक सुरक्षित और सीधा तरीका देता है. यह पूरी तरह से मैनेज किया गया एमसीपी सर्वर, मैनेजमेंट के काम को आसान बनाता है. इससे आपको बेहतर एजेंट बनाने पर ध्यान देने में मदद मिलती है.

2. सेटअप और ज़रूरी शर्तें

इस पूरे लैब को कमांड लाइन पर चलाया जा सकता है. एनवायरमेंट शुरू करने के लिए, Cloud Shell का इस्तेमाल किया जा सकता है. इसके लिए, कंसोल में सबसे ऊपर दाईं ओर मौजूद प्रॉम्प्ट आइकॉन पर क्लिक करें.

डिफ़ॉल्ट प्रोजेक्ट और 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 की सुविधा वाले देशों या इलाकों में से किसी एक का नाम डालें.

यहां ऐसे एनवायरमेंट वैरिएबल दिए गए हैं जिनका इस्तेमाल इस कोडलैब में किया जाएगा. इन्हें एनवायरमेंट फ़ाइल में सेव किया जा सकता है और "सोर्स" किया जा सकता है. पक्का करें कि आपने प्रोजेक्ट आईडी की वैल्यू सही तरीके से सेट की हो. साथ ही, क्षेत्र की वैल्यू भी सेट की हो.

# 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

ध्यान दें: इस स्निपेट को स्क्रिप्ट फ़ाइल के तौर पर सेव करना फ़ायदेमंद होता है. ऐसा इसलिए, ताकि Cloud Shell सेशन रीसेट होने पर, इसे फिर से इस्तेमाल किया जा सके. इसे env.sh के तौर पर सेव करें और बाद के चरणों को चलाते समय एनवायरमेंट वैरिएबल सेट करने के लिए, source env.sh चलाएं. वर्शन कंट्रोल सिस्टम में env.sh को कमिट न करें.

इस कोडलैब के लिए ज़रूरी एपीआई चालू करें. एपीआई में किए गए बदलावों को लागू होने में दो से तीन मिनट लग सकते हैं.

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

3. Agent Development Kit का इस्तेमाल करके डेटा एजेंट बनाना

एजेंट का कोड लिखना

Cloud Shell टर्मिनल या अपने लोकल टर्मिनल से, एजेंटिक ऐप्लिकेशन के लिए रूट डायरेक्ट्री बनाएं:

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 में एजेंट के लिए इंपोर्ट की सुविधा होनी चाहिए.
• requirements.txt Python की डिपेंडेंसी की सूची: google-adk एजेंट डेवलपमेंट किट के लिए और mcp मॉडल कॉन्टेक्स्ट प्रोटोकॉल क्लाइंट के लिए.

इन कमांड की मदद से, __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 Development Kit में adk सीएलआई टूल शामिल होता है. यह एक इंटरैक्टिव टर्मिनल इंटरफ़ेस है, जिसका इस्तेमाल अपने एजेंट को टेस्ट करने के लिए किया जाता है. यह क्विक टेस्टिंग, स्क्रिप्टेड इंटरैक्शन, और CI/CD पाइपलाइन के लिए फ़ायदेमंद है. यह adk web - ADK वेब इंटरफ़ेस जैसी सुविधाएं देता है. यह इंटरफ़ेस, एजेंट को इंटरैक्टिव तरीके से डेवलप और डीबग करने का आसान तरीका है. ADK Web का इस्तेमाल, प्रोडक्शन डिप्लॉयमेंट में नहीं किया जा सकता. हालांकि, इससे एजेंट को आज़माना बहुत आसान हो जाता है.

ध्यान दें: इस निर्देश को चलाने से पहले, पक्का करें कि आपकी मौजूदा डायरेक्ट्री में data_agent डायरेक्ट्री मौजूद हो. इसके लिए, ls निर्देश का इस्तेमाल करें.

यह कमांड 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 पर झलक देखें" मेन्यू आइटम चुनें.

ADK के वेब यूज़र इंटरफ़ेस (यूआई) में, एजेंट से उस डेटा के बारे में पूछें जिसे वह ऐक्सेस कर सकता है:

What data do you have?

यह एजेंट, CitiBike डेटासेट को एक्सप्लोर करने के लिए BigQuery MCP टूल का इस्तेमाल करेगा. इससे आपको Citibike डेटासेट में उपलब्ध टेबल और फ़ील्ड की खास जानकारी मिलेगी.

4. एजेंट को Cloud Run पर डिप्लॉय करना

इस कमांड से, ADK CLI का इस्तेमाल करके एजेंट को Cloud Run पर डिप्लॉय किया जाएगा.

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 \
      --labels dev-tutorial=codelab-cloud-run-adk-gemini-bq-mcp \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}

एजेंट को आज़माएं

हमने अपने एजेंट को डिप्लॉय करने के लिए, --with_ui विकल्प का इस्तेमाल किया. इसने ADK के वेब इंटरफ़ेस की मदद से एजेंट को डिप्लॉय किया है.

1. वेब ब्राउज़र में एजेंट का यूआरएल खोलें. adk deploy कमांड ने इसे वापस कर दिया है. साथ ही, gcloud run services कमांड को रन करके भी यूआरएल को वापस पाया जा सकता है:

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

2. एजेंट से, Citibike के उपलब्ध डेटा के आधार पर जवाब देने के लिए कहें:

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

एजेंट को BigQuery MCP सर्वर का इस्तेमाल करके, Citibike डेटासेट को एक्सप्लोर करना चाहिए. साथ ही, कुछ SQL क्वेरी चलाने के बाद, तीन Citibike स्टेशनों की सूची दिखानी चाहिए.

5. बधाई हो!

कोडलैब पूरा करने के लिए बधाई!

हमारा सुझाव है कि आप Cloud Run का दस्तावेज़ पढ़ें.

हमने क्या-क्या शामिल किया है

• एजेंट डेवलपमेंट किट और Gemini की मदद से, एआई एजेंट बनाने का तरीका
• एजेंट को BigQuery एमसीपी सर्वर से कनेक्ट करने का तरीका.
• एजेंट को Cloud Run पर डिप्लॉय करने का तरीका.

6. व्यवस्थित करें

इस ट्यूटोरियल में इस्तेमाल किए गए संसाधनों के लिए, अपने Google Cloud खाते से शुल्क लिए जाने से बचने के लिए, प्रोजेक्ट या अलग-अलग संसाधनों को मिटाया जा सकता है.

पहला विकल्प: सेवा को मिटाना

Cloud Run सेवा मिटाना

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

दूसरा विकल्प: प्रोजेक्ट मिटाना

पूरे प्रोजेक्ट को मिटाने के लिए, संसाधन मैनेज करें पर जाएं. इसके बाद, दूसरे चरण में बनाया गया प्रोजेक्ट चुनें और मिटाएं को चुनें. प्रोजेक्ट मिटाने पर, आपको Cloud SDK में प्रोजेक्ट बदलने होंगे. gcloud projects list कमांड चलाकर, सभी उपलब्ध प्रोजेक्ट की सूची देखी जा सकती है. अगर आपको कमांड लाइन का इस्तेमाल करना है, तो इस कमांड का भी इस्तेमाल किया जा सकता है:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}