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

1. परिचय

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

• एजेंट प्लैटफ़ॉर्म में, Gemini के साथ एजेंट डेवलपमेंट किट (एडीके) का इस्तेमाल करके, एआई एजेंट बनाने का तरीका.
• BigQuery एमसीपी सर्वर का इस्तेमाल करके, एआई एजेंट को BigQuery में मौजूद स्ट्रक्चर्ड डेटा का ऐक्सेस देने का तरीका.

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

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

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

मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी), लार्ज लैंग्वेज मॉडल (एलएलएम) और एआई ऐप्लिकेशन या एजेंट को बाहरी डेटा सोर्स से कनेक्ट करने के तरीके को स्टैंडर्ड बनाता है. एमसीपी सर्वर, अपने टूल, संसाधनों, और प्रॉम्प्ट का इस्तेमाल करके, कार्रवाइयां करने और अपने बैकएंड सेवा से अपडेट किया गया डेटा पाने की सुविधा देते हैं. BigQuery एमसीपी सर्वर की मदद से, एआई एजेंट, 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 को कमिट न करें.

इस कोडलैब के लिए ज़रूरी एपीआई चालू करें. एपीआई में किए गए बदलावों को लागू होने में 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. एजेंट डेवलपमेंट किट का इस्तेमाल करके, डेटा एजेंट बनाना

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

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

mkdir data_agent

Cloud Shell एडिटर या कोई दूसरा टेक्स्ट एडिटर खोलें. इसके बाद, data_agent डायरेक्ट्री में agent.py बनाएं:

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

डिप्लॉयमेंट के लिए, एडीके को __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

एजेंट को स्थानीय तौर पर आज़माना

एजेंट डेवलपमेंट किट के साथ 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 .

सेवा शुरू होने के बाद, लोकल एडीके वेब पेज खोलें: http://localhost:8080/.

अगर Google Cloud Shell का इस्तेमाल किया जा रहा है, तो वेब झलक बटन पर क्लिक करें. इसके बाद, "पोर्ट 8080 पर झलक देखें" मेन्यू आइटम चुनें.

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

What data do you have?

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

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

इस कमांड से, एडीके सीएलआई का इस्तेमाल करके, एजेंट को 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 \
      --set-env-vars GOOGLE_GENAI_USE_ENTERPRISE=True,GOOGLE_CLOUD_PROJECT="${GOOGLE_CLOUD_PROJECT},GOOGLE_CLOUD_LOCATION=${GOOGLE_CLOUD_LOCATION}"

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

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

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 एमसीपी सर्वर का इस्तेमाल करके, 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}