BigQuery Agent Analytics প্লাগইন দিয়ে ADK Agent এক্সিকিউশন বিশ্লেষণ করুন

1. ভূমিকা

এই কোডল্যাবে, আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে একটি মাল্টি-এজেন্ট সিস্টেম তৈরি করবেন এবং BigQuery এজেন্ট অ্যানালিটিক্স প্লাগইন ব্যবহার করে এজেন্ট পর্যবেক্ষণযোগ্যতা সক্ষম করবেন। আপনি এজেন্টকে কয়েকটি প্রশ্ন জিজ্ঞাসা করবেন , তারপর কথোপকথনের ট্রেস এবং এজেন্ট টুলের ব্যবহার বিশ্লেষণ করতে BigQuery ব্যবহার করবেন।

c8d3754ee87af43f.png

তুমি কি করবে

  • ADK ব্যবহার করে একটি মাল্টি-এজেন্ট রিটেইল সহকারী তৈরি করুন
  • এই এজেন্ট এক্সিকিউশন সম্পর্কে ট্রেস ডেটা ক্যাপচার এবং BigQuery-তে সংরক্ষণ করতে BigQuery এজেন্ট অ্যানালিটিক্স প্লাগইনটি শুরু করুন।
  • BigQuery-তে এজেন্ট লগ ডেটা বিশ্লেষণ করুন

তোমার যা লাগবে

  • ক্রোমের মতো একটি ওয়েব ব্রাউজার
  • বিলিং সক্ষম থাকা একটি Google ক্লাউড প্রকল্প, অথবা
  • একটি জিমেইল অ্যাকাউন্ট। পরবর্তী বিভাগে আপনাকে দেখানো হবে কিভাবে এই কোডল্যাবের জন্য বিনামূল্যে $5 ক্রেডিট রিডিম করবেন এবং একটি নতুন প্রকল্প সেট আপ করবেন।

এই কোডল্যাবটি সকল স্তরের ডেভেলপারদের জন্য, এমনকি নতুনদের জন্যও। আপনি গুগল ক্লাউড শেলের কমান্ড-লাইন ইন্টারফেস এবং ADK ডেভেলপমেন্টের জন্য পাইথন কোড ব্যবহার করবেন। আপনার পাইথন বিশেষজ্ঞ হওয়ার প্রয়োজন নেই, তবে কোড কীভাবে পড়তে হয় তার একটি প্রাথমিক ধারণা আপনাকে ধারণাগুলি বুঝতে সাহায্য করবে।

2. শুরু করার আগে

একটি গুগল ক্লাউড প্রজেক্ট তৈরি করুন

  1. গুগল ক্লাউড কনসোলে , প্রজেক্ট সিলেক্টর পৃষ্ঠায়, একটি গুগল ক্লাউড প্রজেক্ট নির্বাচন করুন বা তৈরি করুন ।

c745d833b0ed52b0.png সম্পর্কে

  1. আপনার ক্লাউড প্রোজেক্টের জন্য বিলিং সক্ষম আছে কিনা তা নিশ্চিত করুন। কোনও প্রোজেক্টে বিলিং সক্ষম আছে কিনা তা কীভাবে পরীক্ষা করবেন তা শিখুন।

ক্লাউড শেল শুরু করুন

ক্লাউড শেল হল গুগল ক্লাউডে চলমান একটি কমান্ড-লাইন পরিবেশ যা প্রয়োজনীয় সরঞ্জামগুলির সাথে প্রিলোডেড থাকে।

  1. গুগল ক্লাউড কনসোলের উপরে "অ্যাক্টিভেট ক্লাউড শেল" এ ক্লিক করুন:

404e4cce0f23e5c5.png সম্পর্কে

  1. ক্লাউড শেলের সাথে সংযুক্ত হয়ে গেলে, ক্লাউড শেলে আপনার প্রমাণীকরণ যাচাই করতে এই কমান্ডটি চালান: 
gcloud auth list
  1. আপনার প্রকল্পটি gcloud এর সাথে ব্যবহারের জন্য কনফিগার করা হয়েছে তা নিশ্চিত করতে নিম্নলিখিত কমান্ডটি চালান: 
gcloud config get project
  1. যদি আপনার প্রকল্পটি প্রত্যাশা অনুযায়ী কনফিগার করা না থাকে, তাহলে আপনার প্রকল্পটি সেট করতে নিম্নলিখিত কমান্ডটি ব্যবহার করুন: 
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

API গুলি সক্ষম করুন

  1. সমস্ত প্রয়োজনীয় API এবং পরিষেবা সক্রিয় করতে এই কমান্ডটি চালান: 
gcloud services enable bigquery.googleapis.com \
cloudresourcemanager.googleapis.com \
aiplatform.googleapis.com
  1. কমান্ডটি সফলভাবে কার্যকর করার পরে, আপনি নীচের দেখানো বার্তার মতো একটি বার্তা দেখতে পাবেন:

"operations/..." অপারেশন সফলভাবে শেষ হয়েছে।

3. ইনস্টলেশন ও সেটআপ

ক্লাউড শেলে ফিরে যান এবং নিশ্চিত করুন যে আপনি আপনার হোম ডিরেক্টরিতে আছেন।

BigQuery-তে adk_logs নামে একটি নতুন ডেটাসেট তৈরি করতে ক্লাউড শেলে নিম্নলিখিত কমান্ডটি চালান:

bq mk --dataset --location=US adk_logs

এখন, একটি ভার্চুয়াল পাইথন পরিবেশ তৈরি করা যাক এবং প্রয়োজনীয় প্যাকেজগুলি ইনস্টল করা যাক।

  1. ক্লাউড শেলে একটি নতুন টার্মিনাল ট্যাব খুলুন এবং adk-agent-observability নামে একটি ফোল্ডার তৈরি এবং নেভিগেট করতে এই কমান্ডটি চালান: 
mkdir adk-agent-observability
cd adk-agent-observability
  1. একটি ভার্চুয়াল পাইথন পরিবেশ তৈরি করুন: 
python -m venv .venv
  1. ভার্চুয়াল পরিবেশ সক্রিয় করুন: 
source .venv/bin/activate
  1. ADK ইনস্টল করুন: 
pip install --upgrade google-adk

৪. একটি ADK অ্যাপ্লিকেশন তৈরি করুন

এবার, আমাদের খুচরা সহকারী এজেন্ট তৈরি করা যাক। এই এজেন্টটি ... এর জন্য ডিজাইন করা হবে।

  1. প্রয়োজনীয় ফোল্ডার এবং ফাইল সহ একটি নতুন এজেন্ট অ্যাপ্লিকেশন স্ক্যাফোল্ড করতে adk create utility কমান্ডটি চালান: 
adk create retail_assistant_app

প্রম্পটগুলি অনুসরণ করুন:

  1. মডেলের জন্য gemini-2.5-flash বেছে নিন।
  2. ব্যাকএন্ডের জন্য Vertex AI বেছে নিন।
  3. আপনার ডিফল্ট Google ক্লাউড প্রজেক্ট আইডি এবং অঞ্চল নিশ্চিত করুন।

একটি নমুনা মিথস্ক্রিয়া নীচে দেখানো হয়েছে:

acc9c6bb436f7025.png সম্পর্কে

  1. ক্লাউড শেলের ওপেন এডিটর বোতামে ক্লিক করে ক্লাউড শেল এডিটর খুলুন এবং নতুন তৈরি ফোল্ডার এবং ফাইলগুলি দেখুন:

a940b7eaf3c9f4b3.png সম্পর্কে

তৈরি করা ফাইলগুলি লক্ষ্য করুন: 

retail_assistant_app/
├── .venv/
└── retail_assistant_app/
    ├── __init__.py
    ├── agent.py
    └── .env
  • init.py: ফোল্ডারটিকে পাইথন মডিউল হিসেবে চিহ্নিত করে।
  • agent.py: প্রাথমিক এজেন্ট সংজ্ঞা ধারণ করে।
  • . env: এই ফাইলটি দেখতে আপনাকে View > Toggle Hidden Files এ ক্লিক করতে হতে পারে।

16a1a92b33f78e6b.png সম্পর্কে

  • .env ফাইলটিতে আপনার প্রকল্পের জন্য পরিবেশগত ভেরিয়েবল রয়েছে, প্রম্পট থেকে সঠিকভাবে সেট করা হয়নি এমন যেকোনো ভেরিয়েবল আপডেট করুন: 
GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>

৫. আপনার এজেন্টকে সংজ্ঞায়িত করুন

এবার একটি শ্রেণিবদ্ধ মাল্টি-এজেন্ট সিস্টেম সংজ্ঞায়িত করা যাক।

  1. রিয়েল টাইম ট্রেন্ড এজেন্ট: বর্তমান ফ্যাশন ট্রেন্ড খুঁজে পেতে গুগল সার্চ ব্যবহার করে।
  2. ইনভেন্টরি ডেটা এজেন্ট: উপলব্ধ পণ্যগুলির জন্য পাবলিক thelook_ecommerce ডেটাসেট অনুসন্ধান করতে BigQuery টুলসেট ব্যবহার করে।
  3. খুচরা সহকারী (রুট) এজেন্ট: ট্রেন্ড এজেন্টের পরামর্শ এবং পণ্যের সাথে মিলের জন্য ইনভেন্টরি এজেন্টের কাছে অনুরোধ করে কর্মপ্রবাহ পরিচালনা করে।

retail_assistant_app/agent.py এর সম্পূর্ণ কন্টেন্ট নিম্নলিখিত কোড দিয়ে প্রতিস্থাপন করুন। 

import os
import uuid
import asyncio
import google.auth
import dotenv
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.tools.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.plugins.bigquery_agent_analytics_plugin import BigQueryAgentAnalyticsPlugin

dotenv.load_dotenv()

# --- 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-2.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-2.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-2.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]
)

৬. BigQuery Agent Analytics প্লাগইন দিয়ে লগ তৈরি করুন

এখন, এক্সিকিউশন ডেটা ক্যাপচার করার জন্য BigQuery Agent Analytics প্লাগইনটি কনফিগার করা যাক।

এটি করার জন্য, আপনাকে App ক্লাসের একটি ইনস্ট্যান্স তৈরি করতে হবে। এই ক্লাসটি আপনার এজেন্টের রানটাইম কন্টেইনার হিসেবে কাজ করে; এটি কথোপকথন লুপ পরিচালনা করে, ব্যবহারকারীর অবস্থা পরিচালনা করে এবং যেকোনো সংযুক্ত প্লাগইন (যেমন আমাদের এজেন্ট অ্যানালিটিক্স লগার) সাজিয়ে তোলে।

নিচের কোডটি:

  • লগিং প্লাগইন শুরু করে: প্রয়োজনীয় সংযোগের বিবরণ সহ BigQueryAgentAnalyticsPlugin তৈরি করে।
  • প্লাগইন ইন্টিগ্রেট করে: App কনস্ট্রাক্টরে ইনিশিয়ালাইজড BigQuery প্লাগইন পাস করে, এজেন্ট এক্সিকিউশন ইভেন্টগুলি স্বয়ংক্রিয়ভাবে ক্যাপচার এবং লগ করা হয় তা নিশ্চিত করে।
  • রান এবং লগ এজেন্ট এক্সিকিউশন: runner.run_async এর মাধ্যমে কথোপকথন প্রবাহ কার্যকর করে, প্লাগইনটি একই সাথে ইভেন্টের সম্পূর্ণ ক্রম সংগ্রহ করে এবং তার রিসোর্স বন্ধ করার আগে BigQuery-তে পাঠায়।

agent.py ফাইলে এজেন্ট সংজ্ঞার নিচে এই কোডটি কপি করে পেস্ট করুন: 

async def main(prompt: str):
    """Runs a conversation with the BigQuery agent using the ADK Runner."""
    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])
    runner = InMemoryRunner(app=app)

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

        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 and event.content.parts[0].text:
                print(f"** {event.author}: {event.content.parts[0].text}")

    except Exception as e:
        print(f"Error in main: {e}")
    finally:
        print("Closing BQ Plugin...")
        await bq_logger_plugin.close()
        print("BQ Plugin closed.")

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

যন্ত্রটি তৈরি হওয়ার পর, এজেন্টকে কীভাবে কাজ করতে হবে তা দেখার সময় এসেছে। কথোপকথনের কর্মপ্রবাহ শুরু করতে স্ক্রিপ্টটি চালান। 

python retail_assistant_app/agent.py

আপনার খুচরা সহকারীকে কর্মপ্রবাহ পরিচালনা করতে দেখা উচিত:

  1. এটি রিয়েল টাইম ট্রেন্ড এজেন্টকে (real_time_agent) লন্ডনের আবহাওয়া সনাক্ত করতে এবং উপযুক্ত ফ্যাশন ট্রেন্ড অনুসন্ধান করতে বলে।
  2. এরপর এটি ইনভেন্টরি ডেটা এজেন্ট (inventory_data_agent) কে thelook_ecommerce BigQuery ডেটাসেট অনুসন্ধানের জন্য অর্পণ করে, যা সেই ট্রেন্ডগুলির সাথে মেলে এমন নির্দিষ্ট পণ্যগুলির জন্য।
  3. অবশেষে, রুট অর্কেস্ট্রেটর ফলাফলগুলিকে একটি চূড়ান্ত সুপারিশে সংশ্লেষিত করে।

এই সব সময়, প্লাগইনটি এজেন্টের এক্সিকিউশন ট্রেস BigQuery-তে স্ট্রিম করছে।

৭. এজেন্ট লগ বিশ্লেষণ করুন

টুল ব্যবহার

আমরা এখন দেখতে পাচ্ছি যে আমাদের এজেন্ট পর্দার আড়ালে কী করছিল! ডেটা BigQuery-তে স্ট্রিম করা হয়েছে এবং বিশ্লেষণের জন্য প্রস্তুত:

  1. গুগল ক্লাউড কনসোলে, BigQuery অনুসন্ধান করুন।
  2. এক্সপ্লোরার ফলকে, আপনার প্রকল্পটি সনাক্ত করুন।
  3. adk_logs ডেটাসেটটি প্রসারিত করুন।
  4. retail_assitant_agent_logs টেবিলটি খুলুন এবং Query এ ক্লিক করুন।

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 সম্পর্কে

৮. [বোনাস] ব্যবহারকারীর অনুভূতি বিশ্লেষণ করুন

এবার আসুন এজেন্টকে দেওয়া ব্যবহারকারীর মতামতের অনুভূতি বিশ্লেষণ করি।

  1. ক্লাউড শেলে, একটি ক্লাউড রিসোর্স সংযোগ তৈরি করুন যাতে BigQuery Vertex AI পরিষেবাগুলির সাথে ইন্টারঅ্যাক্ট করতে পারে: 
bq mk --connection --location=us \
    --connection_type=CLOUD_RESOURCE test_connection

আপনার এইরকম একটি প্রতিক্রিয়া দেখা উচিত:

সংযোগ 517325854360.us.test_connection সফলভাবে তৈরি করা হয়েছে

  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. পরিষ্কার করা

আপনার গুগল ক্লাউড অ্যাকাউন্টে চলমান চার্জ এড়াতে, এই কর্মশালার সময় তৈরি করা রিসোর্সগুলি মুছে ফেলুন।

স্ক্রিপ্ট দ্বারা তৈরি লগিং ডেটাসেটটি মুছুন: 

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

১০. অভিনন্দন

অভিনন্দন! আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) দিয়ে একটি মাল্টি-এজেন্ট সিস্টেম তৈরি করেছেন এবং আপনার এজেন্টের আচরণ ট্র্যাক এবং অডিট করার জন্য BigQuery এজেন্ট অ্যানালিটিক্স প্লাগইন সফলভাবে সংহত করেছেন।

রেফারেন্স ডক্স