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

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

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

एजेंट तीन मुख्य क्षमताओं का इस्तेमाल करता है, जो धीरे-धीरे चालू होती हैं:

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

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

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

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

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

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

यह कोडलैब, उन डेवलपर के लिए है जिन्हें Python और Google Cloud के बारे में कुछ जानकारी है.

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

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

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

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

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

अपना प्रोजेक्ट सेट करना

आपने जो GCP प्रोजेक्ट बनाया है उसमें Cloud Shell Editor खोलें.

इसके बाद, टर्मिनल > नया टर्मिनल बनाएं और अपने प्रोजेक्ट को सेट करने के लिए, यह कमांड चलाएं. बाद की कमांड, इस सेटिंग से प्रोजेक्ट आईडी पढ़ती हैं.

gcloud config set project <INSERT_YOUR_GCP_PROJECT_HERE>

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

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

gcloud services enable \
  aiplatform.googleapis.com \
  bigquery.googleapis.com \
  telemetry.googleapis.com \
  --project=$(gcloud config get project)

• aiplatform.googleapis.com: यह Agent Runtime पर आपके एजेंट को होस्ट करता है. इसमें Gemini Enterprise के सेशन और Memory Bank शामिल हैं. साथ ही, यह Gemini मॉडल को उपलब्ध कराता है
• BigQuery API (bigquery.googleapis.com): सार्वजनिक और निजी डेटासेट के ख़िलाफ़ एसक्यूएल क्वेरी
• Telemetry API (telemetry.googleapis.com): एजेंट की परफ़ॉर्मेंस को मॉनिटर करने के लिए OpenTelemetry ट्रेस

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

ADK इंस्टॉल करना

इस कोडलैब के लिए फ़ोल्डर बनाने और ADK और उससे जुड़ी ज़रूरी चीज़ें इंस्टॉल करने के लिए, टर्मिनल में ये कमांड चलाएं:

mkdir -p ~/adk-deploy-scale
cd ~/adk-deploy-scale
uv init --bare
uv add google-adk google-auth google-cloud-bigquery "google-cloud-aiplatform[agent_engines]"

uv, इस कोडलैब के लिए एक अलग Python एनवायरमेंट बनाता है. इसलिए, आपको कुछ भी चालू करने की ज़रूरत नहीं है. Python कमांड के पहले uv run प्रीफ़िक्स जोड़ें.

google-adk पैकेज में adk सीएलआई टूल शामिल है. इसका इस्तेमाल एजेंट को टेस्ट और डिप्लॉय करने के लिए किया जाएगा. adk deploy, Agent Runtime पर आपका एजेंट बनाने के लिए google-cloud-aiplatform का इस्तेमाल करता है. साथ ही, google-cloud-bigquery, ADK के BigQuery टूल के पीछे मौजूद क्लाइंट लाइब्रेरी है.

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

~/adk-deploy-scale फ़ोल्डर में, एजेंट डायरेक्ट्री बनाएं. बाद के सभी निर्देश, ~/adk-deploy-scale (data_science_agent/ का पैरंट) से चलाएं:

mkdir data_science_agent

इसके बाद, अपने प्रोजेक्ट, एजेंट को डिप्लॉय करने के लिए चुने गए इलाके, और डिप्लॉय किए गए एजेंट की सेटिंग के साथ data_science_agent/.env बनाने के लिए, यह निर्देश चलाएं. adk deploy इस फ़ाइल को पढ़ता है. इसलिए, नया टर्मिनल खोलने पर भी ये सेटिंग काम करती हैं.

cat > ~/adk-deploy-scale/data_science_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_ENTERPRISE=True
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
EOF

• GOOGLE_CLOUD_PROJECT और GOOGLE_CLOUD_LOCATION: आपका प्रोजेक्ट आईडी (gcloud से भरा गया) और वह क्षेत्र जहां एजेंट काम करता है
• GOOGLE_GENAI_USE_ENTERPRISE: ने आपके Google Cloud प्रोजेक्ट के ज़रिए, ADK कॉल Gemini किया है
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT: इसमें पूरे प्रॉम्प्ट इनपुट और एजेंट के जवाबों को लॉग किया जाता है. यह डीबग करने के लिए काम का होता है

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT सेटिंग, Cloud Logging में उपयोगकर्ता के प्रॉम्प्ट और एजेंट के जवाबों का पूरा कॉन्टेंट लॉग करती है. यह डीबग करने के लिए उपयोगी है. हालांकि, इससे संवेदनशील डेटा या व्यक्तिगत पहचान से जुड़ी जानकारी कैप्चर की जा सकती है. प्रोडक्शन में, इसे false पर सेट करें या पक्का करें कि आपके पास डेटा को मैनेज करने की सही नीतियां मौजूद हों.

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

adk-deploy-scale/
  data_science_agent/
    .env
    __init__.py
    agent.py
    requirements.txt    # created in the Deploy step

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

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 एनवायरमेंट वैरिएबल सेट करता है. यह वैरिएबल, स्थानीय तौर पर चलाने पर मौजूद नहीं होता.

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.integrations.bigquery import BigQueryCredentialsConfig
from google.adk.integrations.bigquery import BigQueryToolset
from google.adk.models import Gemini
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from google.genai import types
import google.auth

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
if not PROJECT_ID:
    raise ValueError(
        "GOOGLE_CLOUD_PROJECT environment variable is required. "
        "Add it to data_science_agent/.env: 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 Agent 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 Runtime, 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(
        model="gemini-3.8-flash",
        # gemini-3.8-flash is served from the global endpoint. The agent
        # itself runs in GOOGLE_CLOUD_LOCATION (us-central1).
        client_kwargs={"location": "global"},
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    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 कॉलबैक, हर एजेंट रन के बाद सेशन को मेमोरी बैंक में सेव करता है, ताकि एजेंट आने वाले समय में होने वाले सेशन में कॉन्टेक्स्ट को याद रख सके.
3. ऐप्लिकेशन, रूट एजेंट को डिप्लॉय किए जा सकने वाले ऐप्लिकेशन में रैप करता है. इसे एजेंट रनटाइम इस्तेमाल कर सकता है. name, डायरेक्ट्री के नाम (data_science_agent) से मेल खाना चाहिए. adk web इसका इस्तेमाल, एजेंट को ढूंढने और लोड करने के लिए करता है.
4. निर्देश में एजेंट को बताया जाता है कि SQL क्वेरी के लिए बिलिंग प्रोजेक्ट का इस्तेमाल करें और उपयोगकर्ता की प्राथमिकताओं को याद रखें.
5. Gemini, client_kwargs={"location": "global"} के साथ मॉडल कॉल को ग्लोबल एंडपॉइंट पर भेजता है. ऐसा उन देशों में किया जाता है जहां gemini-3.8-flash उपलब्ध है. एजेंट खुद us-central1 में चलता है: adk deploy, डिप्लॉय किए गए एजेंट पर GOOGLE_CLOUD_LOCATION को उस इलाके के हिसाब से सेट करता है जहां एजेंट को डिप्लॉय किया गया है. इसलिए, मॉडल की जगह को कोड में सेट किया जाता है.

4. एजेंट रनटाइम में डिप्लॉय करना

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

google-adk
google-genai
google-auth
google-cloud-bigquery
python-dotenv
opentelemetry-instrumentation-google-genai
opentelemetry-instrumentation-httpx
opentelemetry-instrumentation-grpc

• google-adk और google-genai: ADK और Gemini क्लाइंट
• google-auth: Google Cloud की मदद से पुष्टि करना
• google-cloud-bigquery: BigQuery क्लाइंट लाइब्रेरी, जिसका इस्तेमाल BigQueryToolset करता है. ADK इसे डिफ़ॉल्ट रूप से इंस्टॉल नहीं करता है.
• python-dotenv: इससे स्टार्टअप के समय .env फ़ाइल लोड होती है
• तीन opentelemetry-instrumentation-* पैकेज, निगरानी से जुड़ी सुविधाएं चालू करते हैं. इनके बारे में आपको बाद में पता चलेगा. ये Gemini मॉडल कॉल और इंटरनल gRPC/HTTP कम्यूनिकेशन को इंस्ट्रुमेंट करते हैं, ताकि आपके एजेंट के ट्रेस टैब पर ट्रेस दिखें.

आपने को स्थानीय तौर पर इंस्टॉल किया है, लेकिन फिर भी अपनी requirements.txt में google-cloud-aiplatform को न जोड़ें. adk deploy इसे आपके लिए जोड़ता है. साथ ही, यह उस एडीके वर्शन को भी जोड़ता है जिसे आपने डिप्लॉय किया है. हालांकि, ऐसा सिर्फ़ तब होता है, जब requirements.txt में यह पहले से मौजूद न हो. इसे खुद से तय करने पर, OpenTelemetry पैकेज के वर्शन में टकराव हो सकता है. इससे इंस्ट्रुमेंटेशन में समस्या आ सकती है और Traces टैब में ट्रेस नहीं दिखते.

adk deploy, पहले से बनाई गई data_science_agent/.env फ़ाइल को भी पढ़ता है और डिप्लॉय किए गए एजेंट पर उसकी सेटिंग सेट करता है.

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

uv run adk deploy agent_engine \
  --project=$(gcloud config get project) \
  --region=us-central1 \
  --display_name="Data Science Agent" \
  --otel_to_cloud \
  data_science_agent

शुरुआत में, आउटपुट में दो पीली लाइनें दिखती हैं, Ignoring GOOGLE_CLOUD_PROJECT in .env ... और Ignoring GOOGLE_CLOUD_LOCATION in .env .... ऐसा होना चाहिए: --project और --region फ़्लैग, .env में मौजूद एक जैसी वैल्यू पर प्राथमिकता पाते हैं.

झंडा	मकसद
--project / --region	टारगेट किया गया Google Cloud प्रोजेक्ट और क्षेत्र
--display_name	Cloud Console में दिखने वाला ऐसा नाम जिसे कोई व्यक्ति आसानी से पढ़ सके
--otel_to_cloud	यह विकल्प, OpenTelemetry ट्रेस और लॉग को Google Cloud में एक्सपोर्ट करता है. साथ ही, डिप्लॉय किए गए एजेंट पर टेलीमेट्री (GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true) चालू करता है

आम तौर पर, इसे लागू होने में 5 से 10 मिनट लगते हैं. प्रोसेस पूरी होने के बाद, आउटपुट में आपके एजेंट का संसाधन नाम (projects/.../reasoningEngines/) और उसे Cloud Console में देखने का लिंक दिखता है.

जब तक यह प्रोसेस पूरी नहीं हो जाती, तब तक Memory Bank के दस्तावेज़ पढ़ें. इससे आपको यह समझने में मदद मिलेगी कि क्रॉस-सेशन मेमोरी कैसे काम करती है.

अगर adk deploy से प्रिंट किया गया लिंक काम नहीं करता है, तो Cloud Console में डिप्लॉयमेंट पेज खोलें और अपने एजेंट पर क्लिक करें.

एजेंट रनटाइम में डिप्लॉय करने पर, दो सुविधाएं अपने-आप चालू हो जाती हैं:

• मेमोरी बैंक: adk deploy एजेंट को उसके एजेंट रनटाइम इंस्टेंस पर सेशन और मेमोरी बैंक से कनेक्ट करता है. PreloadMemoryTool मेमोरी बैंक से डेटा पढ़ता है और _save_memory सेशन को अपने-आप बनाए रखता है.
• निगरानी: Cloud Trace, एजेंट के फ़ैसले लेने के चरणों, टूल कॉल, और इंतज़ार के समय को कैप्चर करता है.

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

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

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get 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 $(gcloud config get project) \
  --member="serviceAccount:${SA}" \
  --role="roles/bigquery.jobUser"

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

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

अगर आपने यह चरण छोड़ दिया, तो डिप्लॉय किया गया एजेंट एसक्यूएल क्वेरी चलाने पर 403 गड़बड़ियां दिखाएगा. bigquery.jobUser भूमिका, डेटा प्रोजेक्ट के बजाय बिलिंग प्रोजेक्ट (आपका प्रोजेक्ट) पर सेट होनी चाहिए.

ध्यान दें: bigquery.dataViewer से, आपके प्रोजेक्ट में मौजूद सभी डेटासेट को पढ़ने का ऐक्सेस मिलता है. प्रोडक्शन के लिए, इस भूमिका को डेटासेट लेवल पर असाइन करें.

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

Google Cloud Console में, डिप्लॉयमेंट पेज खोलें. डिप्लॉय किए गए एजेंट पर क्लिक करें. इसके बाद, Playground टैब पर क्लिक करें.

हर क्वेरी को पूरा होने में 10 से 30 सेकंड लग सकते हैं, क्योंकि एजेंट जवाब देता है, टूल इस्तेमाल करता है, और नतीजे दिखाता है.

BigQuery की सुविधाओं को आज़माएं:

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

7. मेमोरी परसिस्टेंस की जांच करें

प्लेग्राउंड में ही, एजेंट को अपनी पसंद के बारे में बताएं:

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

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

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

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

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

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

अगर एजेंट को आपकी प्राथमिकता याद नहीं है, तो 10 सेकंड इंतज़ार करें और किसी नए सेशन में फिर से कोशिश करें. मेमोरी को सेव करने की प्रोसेस एसिंक्रोनस होती है. इसलिए, इसे पूरा होने में कुछ समय लग सकता है.

8. जांचने की क्षमता के बारे में जानें

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

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

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

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

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

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

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

--otel_to_cloud के साथ डिप्लॉय करने पर, adk deploy एक ऐसा कंटेनर बनाता है जो ADK API सर्वर को OpenTelemetry के साथ चलाता है. एजेंट रनटाइम पर, सर्वर एक OpenTelemetry पाइपलाइन शुरू करता है. यह पाइपलाइन:

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

डिप्लॉय किए गए कंटेनर में ADK और OpenTelemetry SDK टूल और एक्सपोर्टर शामिल है, लेकिन इसमें इंस्ट्रुमेंटेशन पैकेज शामिल नहीं हैं. इसलिए, आपकी requirements.txt सूची में ये तीनों दिखते हैं. इनके बिना, ADK API सर्वर एक चेतावनी लॉग करता है और उन स्पैन को छोड़ देता है.

समस्या का हल

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

1. देखें कि Telemetry API चालू हो: आपने इसे सेटअप के दौरान चालू किया था. इनसे पुष्टि की गई: gcloud services list --enabled --project=$(gcloud config get project) | grep telemetry
2. चेतावनी के लिए Cloud Logging की जांच करें: लॉगिंग > लॉग एक्सप्लोरर पर जाएं और "proceeding without" या "GoogleGenAiSdkInstrumentor" खोजें. अगर किसी इंस्ट्रूमेंटेशन (GenAI, HTTPX या gRPC) के नाम वाली चेतावनी दिखती है, तो इसका मतलब है कि आपके requirements.txt में, मैच करने वाला opentelemetry-instrumentation-* पैकेज मौजूद नहीं है.
3. अपने requirements.txt में google-cloud-aiplatform न जोड़ें. adk deploy इसे अपने-आप जोड़ देता है. इसे खुद से जोड़ने पर, OpenTelemetry पैकेज में टकराव हो सकता है और इंस्ट्रुमेंटेशन चुपचाप बंद हो सकता है.

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

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

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

इस कोडलैब में BigQuery की क्वेरी में सार्वजनिक डेटासेट का इस्तेमाल किया गया है. इसलिए, स्टोरेज का कोई शुल्क नहीं लगता. आपने जिन IAM भूमिकाओं को अनुमति दी है वे प्रोजेक्ट पर बनी रहेंगी. हालांकि, इससे लागत पर कोई असर नहीं पड़ेगा.

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

gcloud projects delete <YOUR_PROJECT_ID>

इसके अलावा, अपने लोकल एनवायरमेंट को क्लीन अप करें:

cd ~
rm -rf ~/adk-deploy-scale

10. बधाई हो

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

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

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

अगले चरण

• अपने निजी BigQuery डेटासेट की क्वेरी करें. इसके लिए, Agent Runtime सेवा एजेंट को अपने डेटा का ऐक्सेस दें
• सुरक्षित सैंडबॉक्स में Python का विश्लेषण करने के लिए, कोड एक्ज़ीक्यूशन जोड़ें
• प्रोडक्शन में अपने एजेंट को मॉनिटर करने के लिए, Cloud Trace observability डैशबोर्ड सेट अप करें
• MCP टूल का इस्तेमाल करके, Google Workspace में नतीजे पब्लिश करना

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

• ADK से जुड़े दस्तावेज़
• एजेंट रनटाइम से जुड़े दस्तावेज़
• Memory Bank से जुड़े दस्तावेज़
• एजेंट रनटाइम की डिप्लॉयमेंट गाइड