BigQuery Agent Analytics प्लगिन की मदद से, ADK एजेंट के एक्ज़ीक्यूशन का विश्लेषण करना

1. परिचय

इस कोडलैब में, Agent Development Kit (ADK) का इस्तेमाल करके, कई एजेंट वाला सिस्टम बनाने का तरीका बताया गया है. साथ ही, इसमें BigQuery एजेंट Analytics प्लगिन की मदद से, एजेंट की जांचने की क्षमता को चालू करने का तरीका भी बताया गया है. आपको एजेंट से कई सवाल पूछने होंगे. इसके बाद, बातचीत के ट्रेस और एजेंट टूल के इस्तेमाल का विश्लेषण करने के लिए, BigQuery का इस्तेमाल करें.

c8d3754ee87af43f.png

आपको क्या करना होगा

  • ADK का इस्तेमाल करके, कई एजेंट वाला रीटेल असिस्टेंट बनाना
  • BigQuery Agent Analytics प्लगिन को शुरू करें, ताकि इस एजेंट के एक्ज़ीक्यूशन के बारे में ट्रेस डेटा को BigQuery में कैप्चर और सेव किया जा सके
  • BigQuery में एजेंट के लॉग डेटा का विश्लेषण करना

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

  • कोई वेब ब्राउज़र, जैसे कि Chrome
  • बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट या
  • Gmail खाता. अगले सेक्शन में, इस कोडलैब के लिए 5 डॉलर का मुफ़्त क्रेडिट रिडीम करने और नया प्रोजेक्ट सेट अप करने का तरीका बताया गया है

यह कोडलैब, सभी लेवल के डेवलपर के लिए है. इसमें शुरुआती डेवलपर भी शामिल हैं. एडीके डेवलपमेंट के लिए, Google Cloud Shell में कमांड-लाइन इंटरफ़ेस और Python कोड का इस्तेमाल किया जाएगा. आपको Python का विशेषज्ञ होने की ज़रूरत नहीं है. हालांकि, कोड को पढ़ने की बुनियादी जानकारी होने से, आपको कॉन्सेप्ट समझने में मदद मिलेगी.

2. शुरू करने से पहले

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

  1. Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, Google Cloud प्रोजेक्ट चुनें या बनाएं.

c745d833b0ed52b0.png

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

Cloud Shell शुरू करें

Cloud Shell, Google Cloud में चलने वाला एक कमांड-लाइन एनवायरमेंट है. इसमें ज़रूरी टूल पहले से लोड होते हैं.

  1. Google Cloud Console में सबसे ऊपर मौजूद, Cloud Shell चालू करें पर क्लिक करें:

404e4cce0f23e5c5.png

  1. Cloud Shell से कनेक्ट होने के बाद, Cloud Shell में पुष्टि करने के लिए यह कमांड चलाएं:
gcloud auth list
  1. यह पुष्टि करने के लिए कि आपका प्रोजेक्ट gcloud के साथ इस्तेमाल करने के लिए कॉन्फ़िगर किया गया है, यह निर्देश चलाएं:
gcloud config get project
  1. अगर आपका प्रोजेक्ट आपकी उम्मीद के मुताबिक कॉन्फ़िगर नहीं किया गया है, तो अपना प्रोजेक्ट सेट करने के लिए इस निर्देश का इस्तेमाल करें:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

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

  1. सभी ज़रूरी एपीआई और सेवाओं को चालू करने के लिए, यह निर्देश चलाएं:
gcloud services enable bigquery.googleapis.com \
cloudresourcemanager.googleapis.com \
aiplatform.googleapis.com
  1. कमांड के सही तरीके से लागू होने पर, आपको यहां दिखाया गया मैसेज दिखेगा:

कार्रवाई "operations/..." पूरी हो गई.

3. इंस्टॉल और सेटअप करना

Cloud Shell पर वापस जाएं और पक्का करें कि आप अपनी होम डायरेक्ट्री में हों.

BigQuery में adk_logs नाम का नया डेटासेट बनाने के लिए, Cloud Shell में यह कमांड चलाएं:

bq mk --dataset --location=US adk_logs

अब, एक वर्चुअल Python एनवायरमेंट बनाते हैं और ज़रूरी पैकेज इंस्टॉल करते हैं.

  1. Cloud Shell में एक नया टर्मिनल टैब खोलें. इसके बाद, adk-agent-observability नाम का फ़ोल्डर बनाने और उस पर जाने के लिए, यह निर्देश चलाएं:
mkdir adk-agent-observability
cd adk-agent-observability
  1. वर्चुअल Python एनवायरमेंट बनाएं:
python -m venv .venv
  1. वर्चुअल एनवायरमेंट चालू करें:
source .venv/bin/activate
  1. ADK इंस्टॉल करें:
pip install --upgrade google-adk

4. ADK ऐप्लिकेशन बनाना

अब, हम अपने खुदरा सहायक एजेंट को बनाते हैं. इस एजेंट को ... के लिए डिज़ाइन किया जाएगा

  1. ज़रूरी फ़ोल्डर और फ़ाइलों के साथ नया एजेंट ऐप्लिकेशन बनाने के लिए, adk create utility command चलाएं:
adk create retail_assistant_app

दिए गए निर्देशों का पालन करें:

  1. मॉडल के लिए, gemini-3.5-flash चुनें.
  2. बैकएंड के लिए Vertex AI चुनें.
  3. अपने डिफ़ॉल्ट Google Cloud प्रोजेक्ट आईडी और क्षेत्र की पुष्टि करें.

यहां इंटरैक्शन का एक उदाहरण दिया गया है:

acc9c6bb436f7025.png

  1. Cloud Shell Editor खोलने और नए बनाए गए फ़ोल्डर और फ़ाइलें देखने के लिए, Cloud Shell में 'एडिटर खोलें' बटन पर क्लिक करें:

a940b7eaf3c9f4b3.png

जनरेट की गई फ़ाइलों को नोट करें:

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env
  • init.py: इस फ़ाइल से फ़ोल्डर को Python मॉड्यूल के तौर पर मार्क किया जाता है.
  • agent.py: इसमें एजेंट की शुरुआती परिभाषा शामिल होती है.
  • .env: इस फ़ाइल को देखने के लिए, आपको शायद देखें > छिपी हुई फ़ाइलें टॉगल करें पर क्लिक करना पड़े

16a1a92b33f78e6b.png

  • .env फ़ाइल में आपके प्रोजेक्ट के लिए एनवायरमेंट वैरिएबल होते हैं. ऐसे वैरिएबल अपडेट करें जिन्हें प्रॉम्प्ट से सही तरीके से सेट नहीं किया गया था. पक्का करें कि आपकी जगह की जानकारी, ग्लोबल या एक से ज़्यादा देशों/इलाकों के हिसाब से सेट हो.जैसे, us या eu. ऐसा इसलिए, क्योंकि gemini-3.5-flash फ़िलहाल इन्हीं देशों/इलाकों के हिसाब से काम करता है.
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us

5. अपने एजेंट के बारे में जानकारी देना

अब हम एक हैरारिकल मल्टी-एजेंट सिस्टम को परिभाषित करते हैं.

  1. रीयल टाइम ट्रेंड एजेंट: यह Google Search का इस्तेमाल करके, फ़ैशन के मौजूदा ट्रेंड के बारे में जानकारी देता है.
  2. इन्वेंट्री डेटा एजेंट: यह BigQuery टूलसेट का इस्तेमाल करके, उपलब्ध प्रॉडक्ट के लिए thelook_ecommerce के सार्वजनिक डेटासेट से क्वेरी करता है.
  3. खुदरा दुकान के असिस्टेंट (रूट) एजेंट: यह वर्कफ़्लो को व्यवस्थित करता है. इसके लिए, यह ट्रेंड एजेंट से सलाह लेता है और इन्वेंट्री एजेंट से मिलते-जुलते प्रॉडक्ट के बारे में पूछता है.

retail_assistant_app/agent.py के पूरे कॉन्टेंट की जगह यह कोड डालें.

import os
import uuid
import asyncio
import google.auth
import dotenv
import warnings
from google.genai import types
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from google.adk.tools import AgentTool, google_search
from google.adk.integrations.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin
from google.adk.agents.context_cache_config import ContextCacheConfig

dotenv.load_dotenv()

# Suppress experimental and AFC warnings
warnings.filterwarnings("ignore", message=".*\\[EXPERIMENTAL\\].*")
warnings.filterwarnings("ignore", message=".*Direct use of automatic function calling.*")

# --- Configuration ---

PROJECT_ID = os.getenv('GOOGLE_CLOUD_PROJECT', 'project_not_set')
DATASET_ID = "adk_logs"
TABLE_ID = "retail_assistant_agent_logs"
APP_NAME = "retail_assistant_agent"
USER_ID = "test_user"

# --- Toolsets ---

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

# --- Agents ---

# 1. Trend Spotter
real_time_agent = Agent(
   name="real_time_agent",
   model="gemini-3.5-flash",
    description="Researches external factors like weather, local events, and current fashion trends.",
   instruction="""
       You are a real-time research agent.
       Use Google Search to find real-time information relevant to the user's request,
       such as the current weather in their location or trending styles.
   """,
   tools=[google_search]
)

# 2. Inventory Manager
inventory_data_agent = Agent(
   name="inventory_data_agent",
   model="gemini-3.5-flash",
   description="Oversees product inventory in the BigQuery `thelook_ecommerce` dataset to find available items and prices.",
   instruction=f"""
   You manage the inventory. You have access to the `bigquery-public-data.thelook_ecommerce` dataset via the BigQuery toolset.
   Run all BigQuery queries the project id of: '{PROJECT_ID}'

   Your workflow:
   1. Look at the products table.
   2. Find items that match the requirements, factor in the results from the trend_setter agent if there are any.
   3. Return with a user friendly response, including the list of specific products and prices.
   """,
   tools=[bigquery_toolset]
)

# 3. Root Orchestrator
root_agent = Agent(
   name="retail_assistant",
   model="gemini-3.5-flash",
   description="The primary orchestrator, responsible for handling user input, delegating to sub-agents, and synthesizing the final product recommendation.",
   instruction="""
   You are a Retail Assistant.
   You can ask the 'real_time_agent' agent for any realtime information needed, or style advice, include any information provided by the user.
   You should ask the 'inventory_data_agent' agent to find a maximum of 3 available items matching that style.
   Combine the results into a recommendation.
   """,
   tools=[AgentTool(agent=real_time_agent)],
   sub_agents=[inventory_data_agent]
)

6. BigQuery Agent Analytics प्लगिन की मदद से लॉग जनरेट करना

अब, एक्ज़ीक्यूशन डेटा कैप्चर करने के लिए, BigQuery Agent Analytics प्लगिन को कॉन्फ़िगर करें.

इसके लिए, आपको App क्लास का एक इंस्टेंस बनाना होगा. यह क्लास, आपके एजेंट के लिए रनटाइम कंटेनर के तौर पर काम करती है. यह बातचीत के लूप को मैनेज करती है, उपयोगकर्ता की स्थिति को हैंडल करती है, और अटैच किए गए किसी भी प्लगिन (जैसे, हमारे एजेंट के आंकड़ों का लॉग करने वाला प्लगिन) को व्यवस्थित करती है.

नीचे दिया गया कोड:

  • Logging Plugin को शुरू करता है: ज़रूरी कनेक्शन की जानकारी के साथ BigQueryAgentAnalyticsPlugin बनाता है.
  • प्लगिन को इंटिग्रेट करता है: शुरू किए गए BigQuery प्लगिन को App कंस्ट्रक्टर में पास करता है. इससे यह पक्का होता है कि एजेंट के एक्ज़ीक्यूशन इवेंट अपने-आप कैप्चर और लॉग हो जाएं.
  • एजेंट के एक्ज़ीक्यूशन को चलाने और लॉग करने की सुविधा: यह सुविधा, runner.run_async के ज़रिए बातचीत के फ़्लो को एक्ज़ीक्यूट करती है. साथ ही, प्लगिन अपने संसाधनों को बंद करने से पहले, इवेंट के पूरे क्रम को इकट्ठा करके BigQuery को भेजता है.

इस कोड को कॉपी करके, agent.py फ़ाइल में एजेंट की परिभाषाओं के नीचे चिपकाएं:

async def main(prompt: str):
    print(f"\n{'='*60}")
    print(f"👤 USER: {prompt}")
    print(f"{'='*60}")

    print("📊 [Analytics]: Initializing BigQuery Agent Analytics Plugin...")
    bq_logger_plugin = BigQueryAgentAnalyticsPlugin(
        project_id=PROJECT_ID, dataset_id=DATASET_ID, table_id=TABLE_ID
    )

    app = App(
        name=APP_NAME,
        root_agent=root_agent,
        plugins=[bq_logger_plugin],
        context_cache_config=ContextCacheConfig()
    )
    runner = InMemoryRunner(app=app)

    try:
        session_id = f"{USER_ID}_{uuid.uuid4().hex[:8]}"

        print(f"⚙️  [System]: Initializing session {session_id}...")
        print("📊 [Analytics]: Streaming execution trace to BigQuery...")

        my_session = await runner.session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID, session_id=session_id
        )

        async for event in runner.run_async(
            user_id=USER_ID,
            new_message=types.Content(
                role="user", parts=[types.Part.from_text(text=prompt)]
            ),
            session_id=my_session.id,
        ):
            if event.content.parts:
                for part in event.content.parts:
                    if part.text:
                        print(f"\n🤖 [{event.author}]: {part.text.strip()}")
                    elif part.function_call:
                        print(f"\n🛠️  [{event.author}] used tool: {part.function_call.name}")

    except Exception as e:
        print(f"\n❌ Error in main: {e}")
    finally:
        print("\n📊 [Analytics]: Closing BigQuery Plugin and flushing logs...")
        await bq_logger_plugin.close()
        print("📊 [Analytics]: BQ Plugin closed successfully.")
        print(f"✅ [System]: Finished processing prompt.")

async def run_all_prompts():
    """Runs all prompts in a single event loop."""
    prompts = [
        "what outfits do you have available that are suitable for the weather in london this week?",
        "You are such a cool agent! I need a gift idea for my friend who likes yoga.",
        "I'd like to complain - the products sold here are not very good quality!"
    ]
    for prompt in prompts:
        await main(prompt)

if __name__ == "__main__":
    asyncio.run(run_all_prompts())

एजेंट को चलाने से पहले, पक्का करें कि आपके venv में ज़रूरी डिपेंडेंसी इंस्टॉल हों. इसके लिए, यह कमांड चलाएं:

pip install "google-adk[bigquery-analytics]"

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

python retail_assistant_app/agent.py

आपको दिखेगा कि खुदरा स्टोर में काम करने वाला असिस्टेंट, वर्कफ़्लो को व्यवस्थित कर रहा है:

  1. यह रीयल टाइम ट्रेंड एजेंट (real_time_agent) से, लंदन में मौसम की जानकारी देने और उसके हिसाब से फ़ैशन के रुझान खोजने के लिए कहता है.
  2. इसके बाद, यह इन्वेंट्री डेटा एजेंट (inventory_data_agent) को यह काम सौंपता है कि वह उन खास प्रॉडक्ट के लिए thelook_ecommerce BigQuery डेटासेट से क्वेरी करे जो उन रुझानों से मेल खाते हैं.
  3. आखिर में, रूट ऑर्केस्ट्रेटर, नतीजों को मिलाकर एक फ़ाइनल सुझाव तैयार करता है.

इस दौरान, प्लगिन एजेंट के एक्ज़ीक्यूशन ट्रेस को BigQuery में स्ट्रीम करता है.

7. एजेंट के लॉग का विश्लेषण करना

टूल का इस्तेमाल

अब हमें पता चल गया है कि हमारा एजेंट पर्दे के पीछे क्या कर रहा था! डेटा को BigQuery में स्ट्रीम कर दिया गया है और अब उसका विश्लेषण किया जा सकता है:

  1. Google Cloud Console में, BigQuery खोजें.
  2. एक्सप्लोरर पैनल में, अपना प्रोजेक्ट ढूंढें.
  3. adk_logs डेटासेट को बड़ा करें.
  4. retail_assitant_agent_logs टेबल खोलें और क्वेरी पर क्लिक करें.

a2de3b52da21855f.png

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

SELECT
  -- Extract the tool name directly from the JSON key "tool"
  JSON_VALUE(content, '$.tool') AS tool_name,
  -- Count every time a tool finished (successfully or with an error)
  COUNT(*) AS total_finished_runs,
  -- Count as a failure if  event_type is ERROR, result object contains a status of 'ERROR', or error_details exist
  COUNTIF(
    event_type = 'TOOL_ERROR' OR
    JSON_VALUE(content, '$.result.status') = 'ERROR' OR
    JSON_VALUE(content, '$.result.error_details') IS NOT NULL
  ) AS failure_count
FROM
  `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type IN ('TOOL_COMPLETED', 'TOOL_ERROR')
GROUP BY
  1;

इस नतीजे को चार्ट के तौर पर देखने के लिए, विज़ुअलाइज़ेशन पर क्लिक करें (आपके नतीजे अलग-अलग हो सकते हैं):

2e8d009e3e0459ed.png

टोकन का इस्तेमाल

अपने एजेंटों की लागत का अनुमान लगाने के लिए, हर एजेंट के इस्तेमाल किए गए प्रॉम्प्ट टोकन और कैंडिडेट टोकन को इकट्ठा किया जा सकता है:

SELECT
 t.agent,
 SUM(LAX_INT64(t.content.usage.prompt)) AS prompt_tokens,
 SUM(LAX_INT64(t.content.usage.completion)) AS completion_tokens
FROM
 `adk_logs.retail_assistant_agent_logs` AS t
WHERE
 t.event_type = 'LLM_RESPONSE'
 -- Filter for records that actually contain usage metadata
 AND t.content.usage IS NOT NULL
GROUP BY 1;

इस डेटा को चार्ट के तौर पर देखने के लिए, विज़ुअलाइज़ेशन पर क्लिक करें (आपके नतीजे अलग-अलग हो सकते हैं):

134dc090ba55372d.png

8. [बोनस] उपयोगकर्ता के सेंटीमेंट का विश्लेषण करना

अब हम एजेंट को दिए गए उपयोगकर्ता के इनपुट के बारे में विश्लेषण करेंगे.

  1. Cloud Shell में, क्लाउड रिसॉर्स कनेक्शन बनाएं, ताकि BigQuery, Vertex AI की सेवाओं के साथ इंटरैक्ट कर सके:
bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

आपको इस तरह का जवाब दिखेगा:

Connection 517325854360.us.test_connection successfully created

  1. क्लाउड संसाधन कनेक्शन बनाने के लिए:
export SERVICE_ACCOUNT_EMAIL=$(bq show --format=prettyjson --connection us.test_connection | grep "serviceAccountId" | cut -d '"' -f 4)
  1. यह पुष्टि करने के लिए कि सेवा खाता बन गया है, यह कमांड चलाएं:
echo $SERVICE_ACCOUNT_EMAIL

आपको अपना सेवा खाता दिखेगा:

c4a155d9d005e3d8.jpeg

  1. संसाधन कनेक्शन सेवा खाते को, प्रोजेक्ट-लेवल की वे अनुमतियां दें जो Vertex AI के साथ इंटरैक्ट करने के लिए ज़रूरी हैं:
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/bigquery.connectionUser' && \
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
    --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" \
    --role='roles/aiplatform.user'

अनुमतियां लागू होने में कुछ मिनट लग सकते हैं. इसके बाद, BigQuery पर वापस जाएं और उपयोगकर्ता की भावना का विश्लेषण करने के लिए, AI.SCORE फ़ंक्शन वाली यह क्वेरी चलाएं:

SELECT
 timestamp,
 user_id,
 content,
 AI.SCORE((
   'What is the sentiment of the user in this text:', JSON_VALUE(content.text_summary),
   'Use a scale from 1 to 5.'),
 connection_id => 'us.test_connection') AS user_sentiment
FROM
 `adk_logs.retail_assistant_agent_logs`
WHERE
  event_type = 'USER_MESSAGE_RECEIVED'
ORDER BY
 user_sentiment DESC;

AI.SCORE फ़ंक्शन, उपयोगकर्ता के हर इनपुट के लिए 1 से 5 के बीच की भावना की वैल्यू असाइन करेगा. आपको इस तरह के नतीजे दिखेंगे:

4e345b703b86cde8.jpeg

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

अपने Google Cloud खाते से शुल्क लिए जाने से बचने के लिए, इस वर्कशॉप के दौरान बनाए गए संसाधनों को मिटाएं.

स्क्रिप्ट से बनाए गए लॉगिंग डेटासेट को मिटाने के लिए:

bq rm -r -f -d $PROJECT_ID:adk_logs

क्लाउड संसाधन कनेक्शन मिटाने के लिए:

bq rm --connection --project_id=$PROJECT_ID --location=us test_connection

bigquery-adk-codelab डायरेक्ट्री और उसके कॉन्टेंट को हटाने के लिए:

cd ..
rm -rf adk-agent-observability

10. बधाई हो

बधाई हो! आपने Agent Development Kit (ADK) का इस्तेमाल करके, मल्टी-एजेंट सिस्टम बनाया है. साथ ही, आपने BigQuery Agent Analytics प्लगिन को इंटिग्रेट किया है, ताकि एजेंट के व्यवहार को ट्रैक और ऑडिट किया जा सके.

रेफ़रंस दस्तावेज़