एजेंट इंजन पर स्टेटफ़ुल डेटा साइंस एजेंट

1. खास जानकारी

इस कोडलैब में, डेटा साइंस एजेंट बनाया जाएगा. यह एजेंट, BigQuery के सार्वजनिक डेटासेट से असली डेटा की क्वेरी करेगा. साथ ही, अलग-अलग सेशन में आपकी प्राथमिकताओं को याद रखेगा. इसके बाद, इसे Agent Engine में डिप्लॉय किया जाएगा. यह Google Cloud की पूरी तरह से मैनेज की जाने वाली सेवा है, जो इन्फ़्रास्ट्रक्चर, स्केलिंग, और सेशन मैनेजमेंट को हैंडल करती है.

यह एजेंट, तीन मुख्य क्षमताओं का इस्तेमाल करता है. ये क्षमताएं, क्रम से ऐक्टिवेट होती हैं:

  • BigQuery Toolset: यह एजेंट, स्कीमा एक्सप्लोर करता है और BigQuery के असली डेटासेट के ख़िलाफ़ एसक्यूएल क्वेरी चलाता है. यह सुविधा, स्थानीय तौर पर और डिप्लॉय करने के बाद, दोनों तरह से काम करती है.
  • Memory Bank: डिप्लॉय करने के बाद, एजेंट, अलग-अलग सेशन में उपयोगकर्ता की प्राथमिकताओं और कॉन्टेक्स्ट को याद रखता है.
  • ऑब्ज़र्वेबिलिटी: Cloud Trace, OpenTelemetry इंस्ट्रूमेंटेशन के ज़रिए, एजेंट के तर्क देने के चरणों, टूल कॉल, और लेटेंसी को कैप्चर करता है.

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

  • असली डेटा को ऐक्सेस करने के लिए, BigQueryToolset की मदद से ADK एजेंट बनाने का तरीका
  • अलग-अलग सेशन में डेटा को सेव रखने के लिए, Memory Bank को कॉन्फ़िगर करने का तरीका
  • adk deploy की मदद से, अपने एजेंट को Agent Engine में डिप्लॉय करने का तरीका
  • डिप्लॉय किए गए एजेंट के सेवा खाते के लिए, IAM अनुमतियां देने का तरीका
  • मेमोरी को सेव रखने की सुविधा और ऑब्ज़र्वेबिलिटी की जांच करने का तरीका

आपको किन चीज़ों की ज़रूरत होगी

  • बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट
  • Google Cloud SDK (gcloud सीएलआई)
  • Chrome जैसे वेब ब्राउज़र
  • uv (Python पैकेज मैनेजर)
  • Python 3.12 या इससे नया वर्शन (ज़रूरत पड़ने पर, uv इसे अपने-आप इंस्टॉल कर लेता है)

ADK (एजेंट डेवलपमेंट किट), एआई एजेंट बनाने के लिए Google का फ़्रेमवर्क है. इस कोडलैब में, ADK का इस्तेमाल करके एक एजेंट बनाया जाएगा और उसे Agent Engine में डिप्लॉय किया जाएगा.

यह कोडलैब, इंटरमीडिएट लेवल के डेवलपर के लिए है. इन्हें Python और Google Cloud के बारे में थोड़ी जानकारी है.

इस कोडलैब को पूरा करने में करीब 30 मिनट लगते हैं. इसमें डिप्लॉयमेंट के लिए 5 से 10 मिनट शामिल हैं.

इस कोडलैब में बनाए गए संसाधनों की लागत, पांच डॉलर से कम होनी चाहिए.

2. अपना एनवायरमेंट सेट अप करने का तरीका

Google Cloud प्रोजेक्ट बनाएं

  1. Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, कोई Google Cloud प्रोजेक्ट चुनें या बनाएं.
  2. पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो. किसी प्रोजेक्ट के लिए बिलिंग चालू है या नहीं, यह देखने का तरीका जानें.

एनवायरमेंट वैरिएबल सेट करना

बनाए गए GCP प्रोजेक्ट में, Cloud Shell एडिटर खोलें.

इसके बाद, टर्मिनल > नया टर्मिनल बनाएं और ये कमांड चलाएं.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=True

एपीआई चालू करें

टर्मिनल में यह कमांड चलाएं.

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$GOOGLE_CLOUD_PROJECT
  • AI Platform API (aiplatform.googleapis.com) — Agent Engine की होस्टिंग
  • BigQuery API (bigquery.googleapis.com) — सार्वजनिक और निजी डेटासेट के ख़िलाफ़ एसक्यूएल क्वेरी
  • Telemetry API (telemetry.googleapis.com) — एजेंट की ऑब्ज़र्वेबिलिटी के लिए OpenTelemetry ट्रेस

वर्चुअल एनवायरमेंट बनाना और ADK इंस्टॉल करना

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install google-adk google-auth

google-adk पैकेज में, adk सीएलआई टूल शामिल होता है. इसका इस्तेमाल, एजेंट की जांच करने और उसे डिप्लॉय करने के लिए किया जाएगा.

3. एजेंट बनाना

एजेंट के लिए, नया प्रोजेक्ट डायरेक्ट्री बनाएं. इसके बाद के सभी कमांड, इस वर्किंग डायरेक्ट्री से चलाए जाने चाहिए (यह data_science_agent/ की पैरंट डायरेक्ट्री है):

mkdir data_science_agent

आपकी डायरेक्ट्री का फ़ाइनल स्ट्रक्चर ऐसा दिखेगा:

./
  data_science_agent/
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step
    .env                # created in the Deploy step

अब __init__.py और agent.py बनाएं. इसके बाद, डिप्लॉयमेंट के चरण में requirements.txt और .env जोड़ें.

data_science_agent/__init__.py बनाएं. यह फ़ाइल ज़रूरी है, ताकि ADK आपके एजेंट को ढूंढ सके और लोड कर सके:

from . import agent  # noqa: F401 — required by `adk eval` and `adk web`

data_science_agent/agent.py बनाएं:

यह एजेंट, डेटा निकालने की सुविधा के लिए BigQuery से कनेक्ट होता है और सेशन को Memory Bank में सेव रखता है.

डिप्लॉय करने पर, मेमोरी अपने-आप ऐक्टिवेट हो जाती है. GOOGLE_CLOUD_AGENT_ENGINE_ID एनवायरमेंट वैरिएबल, Agent Engine रनटाइम से सेट होता है. स्थानीय तौर पर चलाने पर, यह मौजूद नहीं होता.

from __future__ import annotations

import os

from google.adk.agents import LlmAgent
from google.adk.agents.callback_context import CallbackContext
from google.adk.apps import App
from google.adk.tools.bigquery import BigQueryCredentialsConfig
from google.adk.tools.bigquery import BigQueryToolset
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Set it with: export GOOGLE_CLOUD_PROJECT=<your-project-id>"
    )

credentials, _ = google.auth.default()
bq_toolset = BigQueryToolset(credentials_config=BigQueryCredentialsConfig(credentials=credentials))

# GOOGLE_CLOUD_AGENT_ENGINE_ID is set automatically by the Agent Engine runtime.
agent_engine_id = os.getenv("GOOGLE_CLOUD_AGENT_ENGINE_ID")


async def _save_memory(callback_context: CallbackContext) -> None:
    """Persist the session to Memory Bank after each agent run.

    Only activates on Agent Engine where Memory Bank is available.
    """
    if agent_engine_id:
        await callback_context.add_session_to_memory()


root_agent = LlmAgent(
    name="data_science_agent",
    model="gemini-2.5-pro",
    instruction=(
        "You are an expert Data Science Agent. "
        "Your goal is to query enterprise BigQuery datasets, analyze the data, "
        "and summarize your findings. "
        f"When executing SQL queries, use project_id `{PROJECT_ID}` as the "
        "billing project unless the user specifies a different one. "
        "Present results clearly with formatted numbers. "
        "Remember user preferences like preferred regions, date ranges, "
        "or analysis formats across conversations."
    ),
    tools=[bq_toolset, PreloadMemoryTool()],
    after_agent_callback=_save_memory,
)

app = App(
    name="data_science_agent",
    root_agent=root_agent,
)

आइए जानते हैं कि यह कोड क्या करता है:

  1. BigQueryToolset एजेंट को execute_sql, list_table_ids, और get_table_info जैसे टूल देता है. यह स्कीमा एक्सप्लोर कर सकता है और किसी भी डेटासेट की क्वेरी कर सकता है जिसे कॉल करने वाले व्यक्ति के पास ऐक्सेस करने की अनुमति हो.
  2. PreloadMemoryTool , एलएलएम को कॉल करने से पहले, काम की यादें अपने-आप वापस पा लेता है. इसके लिए, यह Memory Bank में उपयोगकर्ता के मैसेज से जुड़ा कॉन्टेंट खोजता है. _save_memory कॉलबैक, एजेंट के हर रन के बाद सेशन को Memory Bank में सेव रखता है, ताकि एजेंट, आने वाले सेशन में कॉन्टेक्स्ट को याद रख सके.
  3. App , रूट एजेंट को एक ऐसे ऐप्लिकेशन में रैप करता है जिसे Agent Engine डिप्लॉय कर सकता है. name , डायरेक्ट्री के नाम (data_science_agent) से मेल खाना चाहिए. adk web इसका इस्तेमाल, एजेंट को ढूंढने और लोड करने के लिए करता है.
  4. instruction , एजेंट को एसक्यूएल क्वेरी के लिए बिलिंग प्रोजेक्ट का इस्तेमाल करने और उपयोगकर्ता की प्राथमिकताओं को याद रखने के लिए कहता है.

4. Agent Engine में डिप्लॉय करना

data_science_agent डायरेक्ट्री में, requirements.txt फ़ाइल बनाएं:

google-adk>=1.26.0
google-genai>=1.27.0
google-auth>=2.0.0
python-dotenv>=1.1.0
opentelemetry-instrumentation-fastapi
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc
  • google-adk और google-genai — ADK फ़्रेमवर्क और Gemini क्लाइंट
  • google-auth — Google Cloud की पुष्टि करना
  • python-dotenv — स्टार्टअप पर .env फ़ाइल लोड करता है
  • opentelemetry-instrumentation-* के चार पैकेज, ऑब्ज़र्वेबिलिटी की उन सुविधाओं को चालू करते हैं जिन्हें बाद में एक्सप्लोर किया जाएगा. ये FastAPI एचटीटीपी अनुरोधों, Gemini मॉडल कॉल, और इंटरनल gRPC/एचटीटीपी कम्यूनिकेशन को इंस्ट्रूमेंट करते हैं, ताकि ट्रेस, Agent Engine के ट्रेस टैब में दिखें.

डिप्लॉय किए गए एजेंट पर टेलीमेट्री चालू करने के लिए, data_science_agent डायरेक्ट्री में .env फ़ाइल बनाएं:

GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
  • GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY — Agent Engine रनटाइम में OpenTelemetry पाइपलाइन को ऐक्टिवेट करता है.
  • OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT — पूरे प्रॉम्प्ट इनपुट और एजेंट के जवाब लॉग करता है. यह डीबग करने के लिए काम का है.

एजेंट को डिप्लॉय करें. आखिरी आर्ग्युमेंट data_science_agent , वह डायरेक्ट्री है जिसमें आपके एजेंट का कोड है:

adk deploy agent_engine \
  --project=$GOOGLE_CLOUD_PROJECT \
  --region=$GOOGLE_CLOUD_LOCATION \
  --display_name="Data Science Agent" \
  --trace_to_cloud \
  --otel_to_cloud \
  data_science_agent

फ़्लैग

मकसद

--project / --region

टारगेट Google Cloud प्रोजेक्ट और इलाका

--display_name

Cloud Console में दिखने वाला, आसानी से पढ़ा जा सकने वाला नाम

--trace_to_cloud

एजेंट स्पैन के लिए, Cloud Trace एक्सपोर्टर को चालू करता है

--otel_to_cloud

OpenTelemetry इंस्ट्रूमेंटेशन पाइपलाइन को चालू करता है

Agent Engine में डिप्लॉय करने पर, दो क्षमताएं अपने-आप ऐक्टिवेट हो जाती हैं:

  • Memory Bank: PreloadMemoryTool , Agent Engine के Memory Bank से कनेक्ट होता है और _save_memory , सेशन को अपने-आप सेव रखता है.
  • जांचने की क्षमता: Cloud Trace, एजेंट के गहराई से विश्लेषण के चरणों, टूल कॉल, और इंतज़ार के समय को कैप्चर करता है.

5. BigQuery की अनुमतियां देना

आपको Agent Engine के सेवा खाते को BigQuery का ऐक्सेस देना होगा. डिप्लॉय करने के बाद, एजेंट, Google-मैनेज किए जाने वाले सेवा खाते के तौर पर काम करता है. यह आपके निजी क्रेडेंशियल का इस्तेमाल नहीं करता. इसलिए, इसे एसक्यूएल क्वेरी चलाने के लिए साफ़ तौर पर अनुमतियां देनी होंगी.

PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT \
  --format='value(projectNumber)')

SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Required to execute SQL queries
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

# Required to read table metadata and data
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.dataViewer"

हर कमांड के पूरा होने पर, Updated IAM policy for project [...] प्रिंट होता है.

6. डिप्लॉय किए गए एजेंट की जांच करना

Google Cloud Console में, Agent Engine पेज खोलें. डिप्लॉय किए गए एजेंट पर क्लिक करके, Agent Engine Playground खोलें.

BigQuery की क्षमताओं की जांच करें:

  1. "bigquery-public-data.hacker_news में मौजूद टेबल की सूची दिखाएं"
    • उम्मीद: एजेंट, list_table_ids को कॉल करता है और टेबल के नाम दिखाता है. इनमें full भी शामिल है.
  2. "bigquery-public-data.hacker_news.full में हर साल की पोस्ट की संख्या ढूंढें"
    • उम्मीद: एजेंट, एसक्यूएल क्वेरी के साथ execute_sql को कॉल करता है और साल और पोस्ट की संख्या वाली टेबल दिखाता है.
  3. "पोस्ट में साल-दर-साल कितने प्रतिशत का बदलाव हुआ?"
    • उम्मीद: एजेंट, एसक्यूएल क्वेरी के साथ execute_sql को कॉल करता है. यह क्वेरी, प्रतिशत में बदलाव की गणना करती है और नतीजे दिखाती है.

7. मेमोरी को सेव रखने की सुविधा की जांच करना

Playground में ही रहकर, एजेंट को कोई प्राथमिकता सिखाएं:

  1. "याद रखना कि मेरा पसंदीदा डेटासेट, bigquery-public-data.hacker_news है"
  2. "इसमें कौनसी टेबल हैं?"

मेमोरी को सेव रखने के लिए कुछ सेकंड इंतज़ार करें. एजेंट के जवाब देने के बाद, _save_memory कॉलबैक चलता है.

अब Playground के साइडबार में, "+ नया सेशन" बटन पर क्लिक करके, नया सेशन शुरू करें. इसके बाद, यह सवाल पूछें:

  1. "मेरा पसंदीदा डेटासेट कौनसा है?"

एजेंट को bigquery-public-data.hacker_news याद रखना चाहिए. भले ही, यह बिलकुल नया सेशन हो और इसमें बातचीत का इतिहास न हो. ऐसा इसलिए होता है, क्योंकि:

  • _save_memory , callback_context.add_session_to_memory() के ज़रिए, हर सेशन को Memory Bank में सेव रखता है
  • PreloadMemoryTool , एलएलएम को कॉल करने से पहले, काम की यादें वापस पा लेता है
  • Memory Bank, कॉन्टेंट को सिर्फ़ कीवर्ड के हिसाब से नहीं, बल्कि सिमैंटिक तौर पर मैच करता है

8. ऑब्ज़र्वेबिलिटी के बारे में ज़्यादा जानकारी पाना

Cloud Console में, डिप्लॉय किए गए एजेंट पर जाएं और ट्रेस टैब पर क्लिक करें.

सेशन टेबल दिखाने वाला ट्रेस टैब

आपको सेशन टेबल दिखेगी. इसमें, पिछले चरणों में चलाई गई टेस्ट क्वेरी के सेशन की सूची दिखेगी. टेबल में, हर सेशन के लिए खास जानकारी वाली मेट्रिक दिखती हैं. जैसे, औसत अवधि, मॉडल कॉल, टूल कॉल, टोकन का इस्तेमाल, और गड़बड़ियां.

ट्रेस की जानकारी देखने के लिए, किसी सेशन पर क्लिक करें. इसमें यह जानकारी शामिल होती है:

  • इसके स्पैन का डायरेक्टेड एसाइक्लिक ग्राफ़ (डीएजी) . इसमें एजेंट के तर्क देने, टूल कॉल (BigQuery क्वेरी), और लेटेंसी की सिलसिलेवार जानकारी दिखती है
  • हर स्पैन के लिए इनपुट और आउटपुट . यह सुविधा, .env में OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT एनवायरमेंट वैरिएबल के ज़रिए चालू की जाती है
  • स्पैन आईडी, ट्रेस आईडी, और टाइमिंग जैसे मेटाडेटा एट्रिब्यूट

सभी सेशन में अलग-अलग स्पैन देखने के लिए, स्पैन व्यू पर भी स्विच किया जा सकता है. इसके लिए, सबसे ऊपर मौजूद टॉगल का इस्तेमाल करें.

ट्रेसिंग की सुविधा कैसे काम करती है

--trace_to_cloud और --otel_to_cloud के साथ डिप्लॉय करने पर, Agent Engine रनटाइम, OpenTelemetry पाइपलाइन को शुरू करता है. यह पाइपलाइन:

  1. TracerProvider बनाता है. इसमें OTLP एक्सपोर्टर होता है, जो स्पैन को telemetry.googleapis.com पर भेजता है
  2. आपकी requirements.txt में मौजूद इंस्ट्रूमेंटेशन पैकेज का इस्तेमाल करके, मुख्य लाइब्रेरी (FastAPI, Gemini, httpx, gRPC) से स्पैन कैप्चर करता है. रनटाइम, साफ़ तौर पर google-genai को इंस्ट्रूमेंट करता है, जबकि अन्य लाइब्रेरी, OpenTelemetry की ऑटो-डिस्कवरी के ज़रिए योगदान देती हैं
  3. स्पैन को बैच करता है और Telemetry API में एक्सपोर्ट करता है. यहां, ट्रेस टैब उन्हें पढ़ता है

Agent Engine की बेस इमेज, OpenTelemetry SDK और एक्सपोर्टर उपलब्ध कराती है. हालांकि, इसमें इंस्ट्रूमेंटेशन पैकेज शामिल नहीं होते. इसलिए, आपकी requirements.txt में चारों पैकेज शामिल होने चाहिए. इनके बिना, कोई स्पैन नहीं बनता और कोई ट्रेस नहीं दिखता.

समस्या का हल

अगर कुछ मिनट बाद भी कोई ट्रेस नहीं दिखता है, तो:

  1. देखें कि Telemetry API चालू है या नहीं — आपने इसे सेटअप के चरण में चालू किया था. इस कमांड से पुष्टि करें: gcloud services list --enabled --project=$GOOGLE_CLOUD_PROJECT | grep telemetry
  2. चेतावनी के लिए Cloud Logging देखें — लॉगिंग > लॉग एक्सप्लोरर पर जाएं और "telemetry enabled but proceeding without" खोजें. अगर आपको GenAI इंस्ट्रूमेंटेशन के बारे में कोई चेतावनी दिखती है, तो आपकी requirements.txt में opentelemetry-instrumentation-google-genai मौजूद नहीं है.
  3. अपने requirements.txt में, google-cloud-aiplatform[agent-engines] को शामिल न करें. ADK डिप्लॉय सीएलआई, इसे अपने-आप जोड़ देता है. इसे किसी दूसरे वर्शन के साथ फिर से जोड़ने पर, OpenTelemetry पैकेज में टकराव हो सकता है और इंस्ट्रूमेंटेशन चुपचाप टूट सकता है.

9. स्टोरेज में जगह बनाएं

लगातार शुल्क से बचने के लिए, इस कोडलैब के दौरान बनाए गए संसाधन मिटाएं.

Cloud Console में, Agent Engine पेज से डिप्लॉय किए गए एजेंट को मिटाएं. अपना एजेंट चुनें और मिटाएं पर क्लिक करें.

अगर आपने इस कोडलैब के लिए कोई प्रोजेक्ट बनाया है, तो इसके बजाय पूरा प्रोजेक्ट मिटाया जा सकता है:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

ज़रूरी नहीं: अपने स्थानीय एनवायरमेंट को साफ़ करें:

deactivate
rm -rf .venv data_science_agent

10. बधाई हो

आपने स्टेटफ़ुल डेटा साइंस एजेंट बनाया है और उसे Agent Engine में डिप्लॉय किया है!

आपने क्या सीखा

  • असली डेटा को ऐक्सेस करने के लिए, BigQueryToolset की मदद से ADK एजेंट बनाने का तरीका
  • PreloadMemoryTool और after_agent_callback का इस्तेमाल करके, Memory Bank की मदद से मेमोरी को सेव रखने की सुविधा चालू करने का तरीका
  • डिप्लॉय किए गए एजेंट के सेवा खाते के लिए, IAM अनुमतियां देने का तरीका
  • Agent Engine में डिप्लॉय करने और Cloud Trace की मदद से ऑब्ज़र्वेबिलिटी चालू करने का तरीका

अगले चरण

रेफ़रंस के लिए दस्तावेज़