এজেন্ট রানটাইমে স্টেটফুল ডেটা সায়েন্স এজেন্ট

১. সংক্ষিপ্ত বিবরণ

এই কোডল্যাবে, আপনি এমন একটি ডেটা সায়েন্স এজেন্ট তৈরি করবেন যা BigQuery পাবলিক ডেটাসেট থেকে আসল ডেটা কোয়েরি করে এবং বিভিন্ন সেশনে আপনার পছন্দগুলো মনে রাখে। এরপর আপনি এটিকে Agent Runtime-এ ডেপ্লয় করবেন, যা একটি সম্পূর্ণ পরিচালিত গুগল ক্লাউড পরিষেবা এবং এটি ইনফ্রাস্ট্রাকচার, স্কেলিং ও সেশন ম্যানেজমেন্টের কাজ সামলায়।

এজেন্টটি তিনটি মূল ক্ষমতা ব্যবহার করে যা ক্রমান্বয়ে সক্রিয় হয়:

• BigQuery টুলসেট : এজেন্টটি স্কিমা অন্বেষণ করে এবং আসল BigQuery ডেটাসেটের উপর SQL কোয়েরি চালায় — এটি স্থানীয়ভাবে এবং ডেপ্লয় করা অবস্থায় উভয় ক্ষেত্রেই কাজ করে।
• মেমরি ব্যাংক : স্থাপন করা হলে, এজেন্ট সংযোগ বিচ্ছিন্ন সেশনগুলোতেও ব্যবহারকারীর পছন্দ এবং প্রাসঙ্গিক তথ্য মনে রাখে।
• পর্যবেক্ষণযোগ্যতা : ক্লাউড ট্রেস ওপেনটেলিমেট্রি ইনস্ট্রুমেন্টেশনের মাধ্যমে এজেন্টের যুক্তির ধাপসমূহ, টুল কল এবং লেটেন্সি ক্যাপচার করে।

আপনি যা শিখবেন

• বাস্তব ডেটা অ্যাক্সেসের জন্য BigQueryToolset ব্যবহার করে কীভাবে একটি ADK এজেন্ট তৈরি করবেন
• ক্রস-সেশন পারসিস্টেন্সের জন্য মেমরি ব্যাংক কীভাবে কনফিগার করবেন
• adk deploy ব্যবহার করে কীভাবে আপনার এজেন্টকে এজেন্ট রানটাইমে স্থাপন করবেন
• ডেপ্লয় করা এজেন্টের সার্ভিস অ্যাকাউন্টের জন্য কীভাবে IAM পারমিশন প্রদান করবেন
• স্মৃতির স্থায়িত্ব এবং পর্যবেক্ষণযোগ্যতা কীভাবে পরীক্ষা করবেন

আপনার যা যা লাগবে

• বিলিং সক্ষম একটি গুগল ক্লাউড প্রজেক্ট
• ক্রোমের মতো একটি ওয়েব ব্রাউজার
• আপনি যদি ক্লাউড শেলের পরিবর্তে আপনার নিজের মেশিনে কোডটি চালান: গুগল ক্লাউড এসডিকে ( gcloud CLI), uv (পাইথন প্যাকেজ ম্যানেজার), এবং পাইথন ৩.১২+ (প্রয়োজনে uv দ্বারা স্বয়ংক্রিয়ভাবে ইনস্টল করা হয়)।

ADK (এজেন্ট ডেভেলপমেন্ট কিট) হলো এআই এজেন্ট তৈরির জন্য গুগলের একটি ফ্রেমওয়ার্ক। এই কোডল্যাবটিতে ADK ব্যবহার করে একটি এজেন্ট তৈরি করা হয়েছে এবং সেটিকে এজেন্ট রানটাইমে স্থাপন করা হয়েছে।

এই কোডল্যাবটি সেইসব মধ্যম স্তরের ডেভেলপারদের জন্য, যাদের পাইথন এবং গুগল ক্লাউড সম্পর্কে কিছুটা ধারণা আছে।

এই কোডল্যাবটি সম্পূর্ণ করতে প্রায় ৩৫ মিনিট সময় লাগে (এর মধ্যে ডেপ্লয়মেন্টের জন্য ৫-১০ মিনিট অন্তর্ভুক্ত)।

এই কোডল্যাবে তৈরি রিসোর্সগুলোর খরচ ৫ ডলারের কম হওয়া উচিত।

২. আপনার পরিবেশ প্রস্তুত করুন

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

1. গুগল ক্লাউড কনসোলের প্রজেক্ট সিলেক্টর পেজে, একটি গুগল ক্লাউড প্রজেক্ট নির্বাচন করুন বা তৈরি করুন ।
2. আপনার ক্লাউড প্রোজেক্টের জন্য বিলিং চালু আছে কিনা তা নিশ্চিত করুন। কোনো প্রোজেক্টে বিলিং চালু আছে কিনা তা কীভাবে পরীক্ষা করবেন, তা জেনে নিন।

আপনার প্রকল্প সেট করুন

আপনার তৈরি করা GCP প্রজেক্টে ক্লাউড শেল এডিটরটি খুলুন।

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

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 : আপনার এজেন্টকে এজেন্ট রানটাইম-এ হোস্ট করে, যার মধ্যে জেমিনি এন্টারপ্রাইজ সেশন এবং মেমোরি ব্যাংক অন্তর্ভুক্ত, এবং জেমিনি মডেলটি পরিবেশন করে।
• BigQuery API ( bigquery.googleapis.com ): পাবলিক এবং প্রাইভেট ডেটাসেটের বিরুদ্ধে SQL কোয়েরি
• টেলিমেট্রি এপিআই ( telemetry.googleapis.com ): এজেন্ট পর্যবেক্ষণযোগ্যতার জন্য ওপেনটেলিমেট্রি ট্রেস

এপিআই সক্রিয়করণ সম্পন্ন হতে এক মিনিট পর্যন্ত সময় লাগতে পারে। পরবর্তী ধাপগুলিতে যদি "এপিআই সক্রিয় করা হয়নি" ত্রুটি দেখতে পান, তবে কিছুক্ষণ অপেক্ষা করুন এবং পুনরায় চেষ্টা করুন।

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 এই কোডল্যাবের জন্য একটি বিচ্ছিন্ন পাইথন পরিবেশ তৈরি করে, তাই আপনাকে কিছু সক্রিয় করতে হবে না। পাইথন কমান্ডের আগে uv run . যোগ করুন।

google-adk প্যাকেজটিতে adk CLI টুল অন্তর্ভুক্ত রয়েছে, যা আপনি এজেন্ট পরীক্ষা ও ডেপ্লয় করতে ব্যবহার করবেন। adk deploy Agent Runtime-এ আপনার এজেন্ট তৈরি করার জন্য google-cloud-aiplatform ব্যবহার করে, এবং google-cloud-bigquery হলো ADK-এর BigQuery টুলগুলোর পেছনের ক্লায়েন্ট লাইব্রেরি।

৩. এজেন্ট তৈরি করুন

~/adk-deploy-scale ফোল্ডারে agent ডিরেক্টরিটি তৈরি করুন। পরবর্তী সমস্ত কমান্ড ~/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 : আপনার গুগল ক্লাউড প্রজেক্টের মাধ্যমে ADK কি জেমিনিকে কল করে?
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT : সম্পূর্ণ প্রম্পট ইনপুট এবং এজেন্ট প্রতিক্রিয়া লগ করে, যা ডিবাগিংয়ের জন্য উপযোগী।

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT সেটিংটি ব্যবহারকারীর প্রম্পট এবং এজেন্টের প্রতিক্রিয়ার সম্পূর্ণ বিষয়বস্তু ক্লাউড লগিং-এ লগ করে। এটি ডিবাগিংয়ের জন্য উপযোগী, কিন্তু এর মাধ্যমে সংবেদনশীল ডেটা বা ব্যক্তিগত শনাক্তকরণ তথ্য (PII) ক্যাপচার হতে পারে। প্রোডাকশনে, এটিকে ' false সেট করুন অথবা নিশ্চিত করুন যে আপনার যথাযথ ডেটা হ্যান্ডলিং পলিসি রয়েছে।

আপনার চূড়ান্ত ডিরেক্টরি কাঠামোটি দেখতে এইরকম হবে:

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

এখন আপনি __init__.py এবং agent.py তৈরি করবেন, তারপর Deploy ধাপে 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-এর সাথে সংযোগ স্থাপন করে এবং সেশনগুলিকে মেমরি ব্যাংকে সংরক্ষণ করে।

ডেপ্লয় করার সময় মেমরি স্বয়ংক্রিয়ভাবে সক্রিয় হয়। এজেন্ট রানটাইম 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 প্রতিটি LLM কলের আগে ব্যবহারকারীর বার্তার সাথে সম্পর্কিত বিষয়বস্তু খুঁজে বের করার জন্য মেমোরি ব্যাংকে অনুসন্ধান করে স্বয়ংক্রিয়ভাবে প্রাসঙ্গিক মেমোরি পুনরুদ্ধার করে। _save_memory কলব্যাকটি প্রতিটি এজেন্ট রানের পরে সেশনটিকে মেমোরি ব্যাংকে সংরক্ষণ করে, যাতে এজেন্ট ভবিষ্যতের সেশনগুলিতে প্রাসঙ্গিক তথ্য স্মরণ করতে পারে।
3. অ্যাপটি রুট এজেন্টকে একটি ডেপ্লয়েবল অ্যাপ্লিকেশনে মোড়কজাত করে, যা এজেন্ট রানটাইম পরিবেশন করতে পারে। name অবশ্যই ডিরেক্টরির নামের ( data_science_agent ) সাথে মিলতে হবে — adk web এজেন্টকে সনাক্ত ও লোড করার জন্য এটি ব্যবহার করে।
4. নির্দেশনাটিতে এজেন্টকে SQL কোয়েরির জন্য বিলিং প্রজেক্ট ব্যবহার করতে এবং ব্যবহারকারীর পছন্দসমূহ মনে রাখতে বলা হয়েছে।
5. client_kwargs={"location": "global"} সহ Gemini মডেল কলগুলিকে গ্লোবাল এন্ডপয়েন্টে পাঠায়, যেখানে gemini-3.8-flash উপলব্ধ। এজেন্টটি নিজে us-central1 এ চলে: adk deploy ডেপ্লয় করা এজেন্টের GOOGLE_CLOUD_LOCATION আপনার ডেপ্লয় করা অঞ্চলের সাথে সেট করে, তাই মডেলের অবস্থান কোডের মাধ্যমে নির্ধারিত হয়।

৪. এজেন্ট রানটাইমে স্থাপন করুন

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 এবং জেমিনি ক্লায়েন্ট
• google-auth : গুগল ক্লাউড প্রমাণীকরণ
• google-cloud-bigquery : এটি হলো BigQuery ক্লায়েন্ট লাইব্রেরি যা BigQueryToolset ব্যবহার করে। ADK এটি ডিফল্টভাবে ইনস্টল করে না।
• python-dotenv : স্টার্টআপের সময় .env ফাইলটি লোড করে।
• তিনটি opentelemetry-instrumentation-* প্যাকেজ সেই পর্যবেক্ষণযোগ্যতার বৈশিষ্ট্যগুলো সক্ষম করে যা আপনি পরবর্তীতে অন্বেষণ করবেন। এগুলো জেমিনি মডেল কল এবং অভ্যন্তরীণ gRPC/HTTP যোগাযোগকে ইনস্ট্রুমেন্ট করে, যাতে আপনার এজেন্টের ট্রেস ট্যাবে ট্রেসগুলো প্রদর্শিত হয়।

আপনার requirements.txt ফাইলে google-cloud-aiplatform যোগ করবেন না , যদিও আপনি এটি স্থানীয়ভাবে ইনস্টল করে থাকেন। adk deploy আপনার জন্য এটি যোগ করে দেয় (আপনি যে ADK সংস্করণ দিয়ে ডেপ্লয় করছেন তার সাথে), কিন্তু শুধুমাত্র তখনই যখন আপনার 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	গুগল ক্লাউড প্রকল্প এবং অঞ্চলকে লক্ষ্য করুন
--display_name	ক্লাউড কনসোলে প্রদর্শিত মানুষের পাঠযোগ্য নাম
--otel_to_cloud	OpenTelemetry ট্রেস এবং লগ Google Cloud-এ এক্সপোর্ট করে, এবং ডেপ্লয় করা এজেন্টে টেলিমেট্রি চালু করে ( GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true )।

ডেপ্লয়মেন্ট হতে সাধারণত ৫-১০ মিনিট সময় লাগে। সম্পূর্ণ হলে, আউটপুটে আপনার এজেন্টের রিসোর্সের নাম ( projects/.../reasoningEngines/ দেখা যাবে। projects/.../reasoningEngines/ এবং ক্লাউড কনসোলে এটি দেখার জন্য একটি লিঙ্ক।

অপেক্ষা করার সময়, ক্রস-সেশন মেমরি কীভাবে কাজ করে সে সম্পর্কে আরও জানতে মেমরি ব্যাংক ডক্স পর্যালোচনা করুন।

যদি adk deploy দ্বারা প্রিন্ট করা লিঙ্কটি কাজ না করে, তাহলে ক্লাউড কনসোলে Deployments পৃষ্ঠাটি খুলুন এবং তার পরিবর্তে আপনার এজেন্টে ক্লিক করুন।

এজেন্ট রানটাইমে স্থাপন করা হলে, দুটি সক্ষমতা স্বয়ংক্রিয়ভাবে সক্রিয় হয়:

• মেমোরি ব্যাংক : adk deploy এজেন্টকে তার এজেন্ট রানটাইম ইনস্ট্যান্সে সেশন এবং মেমোরি ব্যাংকের সাথে সংযুক্ত করে। PreloadMemoryTool মেমোরি ব্যাংক থেকে ডেটা পড়ে এবং _save_memory স্বয়ংক্রিয়ভাবে সেশনগুলোকে স্থায়ী করে।
• পর্যবেক্ষণযোগ্যতা : ক্লাউড ট্রেস এজেন্টের যুক্তির ধাপসমূহ, টুল কল এবং লেটেন্সি ক্যাপচার করে।

৫. BigQuery-কে অনুমতি প্রদান করুন

আপনাকে BigQuery-কে Agent Runtime সার্ভিস এজেন্ট (AI Platform Reasoning Engine Service Agent)-এর অ্যাক্সেস দিতে হবে। ডেপ্লয় করার পর, এজেন্টটি এই গুগল-পরিচালিত সার্ভিস অ্যাকাউন্ট হিসেবে চলে (আপনার ব্যক্তিগত ক্রেডেনশিয়াল দিয়ে নয়), তাই SQL কোয়েরি চালানোর জন্য এটির সুস্পষ্ট অনুমতির প্রয়োজন হয়।

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 [...] প্রিন্ট করে।

আপনি এই ধাপটি এড়িয়ে গেলে, ডেপ্লয় করা এজেন্টটি SQL কোয়েরি চালানোর সময় 403 এরর দেখাবে। bigquery.jobUser রোলটি বিলিং প্রজেক্টে (আপনার প্রজেক্ট) প্রয়োজন, ডেটা প্রজেক্টে নয়।

দ্রষ্টব্য: bigquery.dataViewer আপনার প্রোজেক্টের সমস্ত ডেটাসেটে পঠনযোগ্য অ্যাক্সেস প্রদান করে। প্রোডাকশন ব্যবহারের জন্য, এর পরিবর্তে ডেটাসেট স্তরে এই রোলটি প্রদান করার কথা বিবেচনা করুন।

৬. ডেপ্লয় করা এজেন্টটি পরীক্ষা করুন

গুগল ক্লাউড কনসোলে ডিপ্লয়মেন্টস পেজটি খুলুন। আপনার ডিপ্লয় করা এজেন্টের উপর ক্লিক করুন, তারপর প্লেগ্রাউন্ড ট্যাবে ক্লিক করুন।

এজেন্ট যেহেতু যুক্তি-তর্ক করে, টুলগুলোকে কল করে এবং ফলাফল ফেরত দেয়, তাই প্রতিটি কোয়েরি সম্পন্ন হতে ১০-৩০ সেকেন্ড সময় লাগতে পারে।

BigQuery-এর সক্ষমতা পরীক্ষা করুন:

1. bigquery-public-data.hacker_news-এর টেবিলগুলো তালিকাভুক্ত করুন।
   • প্রত্যাশিত : এজেন্ট list_table_ids কল করবে এবং full নামসহ টেবিলের নামগুলো ফেরত দেবে।
2. bigquery-public-data.hacker_news.full-এ প্রতি বছর পোস্টের সংখ্যা খুঁজুন।
   • প্রত্যাশিত : এজেন্ট একটি SQL কোয়েরি দিয়ে execute_sql কল করবে এবং এটি বছর ও পোস্টের সংখ্যা সম্বলিত একটি টেবিল ফেরত দেবে।
3. গত বছরের তুলনায় পোস্টের সংখ্যায় শতকরা পরিবর্তন কত ছিল?
   • প্রত্যাশিত : এজেন্ট একটি SQL কোয়েরি দিয়ে execute_sql কল করবে, যা শতাংশ পরিবর্তন গণনা করে এবং ফলাফল ফেরত দেবে।

৭. স্মৃতির স্থায়িত্ব পরীক্ষা করুন

প্লেগ্রাউন্ডে থাকাকালীন, এজেন্টকে একটি পছন্দ শিখিয়ে দিন:

1. মনে রাখবেন যে আমার প্রিয় ডেটাসেট হলো bigquery-public-data.hacker_news
2. এতে কী কী টেবিল আছে?

মেমোরি স্থায়ী হওয়ার জন্য কয়েক সেকেন্ড অপেক্ষা করুন (এজেন্টের সাড়া দেওয়ার পর _save_memory কলব্যাকটি চলে)।

এখন প্লেগ্রাউন্ডে 'New Session'-এ ক্লিক করে একটি নতুন সেশন শুরু করুন , তারপর জিজ্ঞাসা করুন:

3. আমার প্রিয় ডেটাসেট কোনটি?

এজেন্টটির bigquery-public-data.hacker_news রিকল করা উচিত, যদিও এটি একটি একদম নতুন সেশন এবং এর কোনো কনভারসেশন হিস্ট্রি নেই। এটি কাজ করে কারণ:

• _save_memory callback_context.add_session_to_memory() এর মাধ্যমে প্রতিটি সেশনকে মেমোরি ব্যাংকে সংরক্ষণ করে।
• PreloadMemoryTool প্রতিটি LLM কলের আগে প্রাসঙ্গিক মেমরি পুনরুদ্ধার করে।
• মেমোরি ব্যাংক শুধু কীওয়ার্ডের মাধ্যমেই নয়, বরং শব্দার্থগতভাবেও বিষয়বস্তু মেলায়।

যদি এজেন্ট আপনার পছন্দ মনে রাখতে না পারে, তবে ১০ সেকেন্ড অপেক্ষা করুন এবং অন্য একটি নতুন সেশনে আবার চেষ্টা করুন। মেমরি পারসিস্টেন্স একটি অ্যাসিঙ্ক্রোনাস প্রক্রিয়া এবং এটি সম্পন্ন হতে কিছুটা সময় লাগতে পারে।

৮. পর্যবেক্ষণযোগ্যতা অন্বেষণ করুন

ক্লাউড কনসোলে, আপনার ডেপ্লয় করা এজেন্টে যান এবং ট্রেসেস ট্যাবে ক্লিক করুন।

আপনি একটি সেশন টেবিল দেখতে পাবেন, যেখানে পূর্ববর্তী ধাপে চালানো টেস্ট কোয়েরিগুলোর সেশনগুলোর তালিকা থাকবে। টেবিলটিতে প্রতিটি সেশনের সারসংক্ষেপ মেট্রিকগুলো দেখানো হয় — যেমন গড় সময়কাল, মডেল কল, টুল কল, টোকেন ব্যবহার এবং যেকোনো ত্রুটি।

একটি সেশনের ট্রেস বিবরণ খতিয়ে দেখতে সেটির উপর ক্লিক করুন, যার মধ্যে অন্তর্ভুক্ত রয়েছে:

• এর স্প্যানগুলোর একটি ডিরেক্টেড অ্যাসাইক্লিক গ্রাফ (DAG) — যা এজেন্টের যুক্তিপ্রক্রিয়া, টুল কল (বিগকোয়েরি কোয়েরি), এবং ল্যাটেন্সির ধাপে ধাপে বিভাজন দেখায়।
• প্রতিটি স্প্যানের জন্য ইনপুট এবং আউটপুট (যা .env ফাইলে থাকা OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT এনভ ভ্যারিয়েবলের মাধ্যমে সক্রিয় করা হয়)।
• স্প্যান আইডি, ট্রেস আইডি এবং টাইমিং-এর মতো মেটাডেটা অ্যাট্রিবিউট

এছাড়াও, সমস্ত সেশন জুড়ে স্বতন্ত্র স্প্যানগুলি দেখতে আপনি স্প্যান ভিউতে (উপরের টগলটি) যেতে পারেন।

একটি কোয়েরি সম্পন্ন হওয়ার পর ট্রেস দেখা যেতে ১-২ মিনিট সময় লাগতে পারে। আপনি যদি এখনও কোনো ট্রেস দেখতে না পান, তবে কিছুক্ষণ অপেক্ষা করুন এবং পৃষ্ঠাটি রিফ্রেশ করুন।

ট্রেসিং কীভাবে কাজ করে

যখন আপনি --otel_to_cloud সহ ডিপ্লয় করেন, adk deploy একটি কন্টেইনার তৈরি করে যা OpenTelemetry চালু থাকা অবস্থায় ADK API সার্ভার চালায়। এজেন্ট রানটাইমে, সার্ভার একটি OpenTelemetry পাইপলাইন ইনিশিয়ালাইজ করে যা:

1. একটি OTLP এক্সপোর্টার সহ একটি TracerProvider তৈরি করে যা telemetry.googleapis.com এ স্প্যান পাঠায়।
2. এজেন্ট রান, মডেল কল এবং টুল কলের জন্য ADK-এর নিজস্ব স্প্যানগুলো রেকর্ড করে, এবং আপনার requirements.txt থেকে তিনটি ইন্সট্রুমেন্টেশন প্যাকেজ ব্যবহার করে মূল লাইব্রেরিগুলো (Gemini, httpx, gRPC) থেকে স্প্যান যোগ করে।
3. ব্যাচ এবং এক্সপোর্টগুলি টেলিমেট্রি এপিআই-তে পাঠানো হয়, যেখানে ট্রেসেস ট্যাব সেগুলি পড়ে।

ডেপ্লয় করা কন্টেইনারটিতে ADK এবং OpenTelemetry SDK ও এক্সপোর্টার অন্তর্ভুক্ত থাকে, কিন্তু ইন্সট্রুমেন্টেশন প্যাকেজগুলো থাকে না । এই কারণেই আপনার requirements.txt ফাইলে এই তিনটিই তালিকাভুক্ত করা আছে। এগুলো ছাড়া, ADK API সার্ভার একটি সতর্কবার্তা লগ করে এবং ওই স্প্যানগুলো এড়িয়ে যায়।

সমস্যা সমাধান

কয়েক মিনিট পরেও যদি কোনো চিহ্ন না দেখা যায়:

1. টেলিমেট্রি এপিআই (Telemetry API) চালু আছে কিনা তা পরীক্ষা করুন : আপনি সেটআপ ধাপে এটি চালু করেছিলেন। এটি দিয়ে যাচাই করুন: gcloud services list --enabled --project=$(gcloud config get project) | grep telemetry
2. সতর্কবার্তার জন্য ক্লাউড লগিং পরীক্ষা করুন : লগিং > লগস এক্সপ্লোরার- এ যান এবং "proceeding without" বা "GoogleGenAiSdkInstrumentor" লিখে অনুসন্ধান করুন। যে সতর্কবার্তায় কোনো ইন্সট্রুমেন্টেশনের (GenAI, HTTPX, বা gRPC) নাম উল্লেখ থাকে, তার মানে হলো আপনার requirements.txt ফাইলে সংশ্লিষ্ট opentelemetry-instrumentation-* প্যাকেজটি অনুপস্থিত।
3. আপনার requirements.txt ফাইলে google-cloud-aiplatform যোগ করবেন না । adk deploy এটি স্বয়ংক্রিয়ভাবে যোগ করে দেয়; নিজে থেকে এটি ঘোষণা করলে OpenTelemetry প্যাকেজের মধ্যে দ্বন্দ্ব সৃষ্টি হতে পারে এবং নীরবে ইন্সট্রুমেন্টেশন ভেঙে যেতে পারে।

৯. পরিষ্কার করা

চলমান চার্জ এড়াতে, এই কোডল্যাব চলাকালীন তৈরি করা রিসোর্সগুলো মুছে ফেলুন।

ক্লাউড কনসোলের ডিপ্লয়মেন্টস পৃষ্ঠা থেকে ডিপ্লয় করা এজেন্টটি মুছে ফেলুন । আপনার এজেন্টটি নির্বাচন করুন এবং ডিলিট-এ ক্লিক করুন।

এই কোডল্যাবের BigQuery কোয়েরিগুলোতে পাবলিক ডেটাসেট ব্যবহার করা হয়েছে, যার জন্য কোনো স্টোরেজ চার্জ লাগে না। আপনার দেওয়া IAM রোলগুলো প্রজেক্টেই থেকে যায়, কিন্তু এর কোনো খরচ হয় না।

আপনি যদি বিশেষভাবে এই কোডল্যাবের জন্য একটি প্রজেক্ট তৈরি করে থাকেন, তাহলে আপনি পুরো প্রজেক্টটি মুছে ফেলতে পারেন:

gcloud projects delete <YOUR_PROJECT_ID>

ঐচ্ছিকভাবে, আপনার স্থানীয় পরিবেশ পরিষ্কার করুন:

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

১০. অভিনন্দন

আপনি একটি স্টেটফুল ডেটা সায়েন্স এজেন্ট তৈরি করে এজেন্ট রানটাইমে স্থাপন করেছেন!

আপনি যা শিখেছেন

• বাস্তব ডেটা অ্যাক্সেসের জন্য BigQueryToolset ব্যবহার করে কীভাবে একটি ADK এজেন্ট তৈরি করবেন
• PreloadMemoryTool এবং after_agent_callback ব্যবহার করে মেমরি ব্যাংকের সাথে পারসিস্টেন্ট মেমরি কীভাবে সক্রিয় করবেন
• ডেপ্লয় করা এজেন্টের সার্ভিস অ্যাকাউন্টের জন্য কীভাবে IAM পারমিশন প্রদান করবেন
• এজেন্ট রানটাইমে কীভাবে ডিপ্লয় করবেন এবং ক্লাউড ট্রেসের মাধ্যমে অবজার্ভেবিলিটি চালু করবেন

পরবর্তী পদক্ষেপ

• এজেন্ট রানটাইম সার্ভিস এজেন্টকে আপনার ডেটাতে অ্যাক্সেস দিয়ে আপনার নিজস্ব ব্যক্তিগত BigQuery ডেটাসেটগুলো কোয়েরি করুন।
• একটি সুরক্ষিত স্যান্ডবক্সে পাইথন বিশ্লেষণ চালানোর জন্য কোড এক্সিকিউশন যোগ করুন।
• প্রোডাকশনে আপনার এজেন্ট নিরীক্ষণ করতে ক্লাউড ট্রেস অবজার্ভেবিলিটি ড্যাশবোর্ড সেট আপ করুন।
• MCP টুল ব্যবহার করে Google Workspace-এ ফলাফল প্রকাশ করুন

রেফারেন্স নথি

• ADK ডকুমেন্টেশন
• এজেন্ট রানটাইম ডকুমেন্টেশন
• মেমরি ব্যাংক ডকুমেন্টেশন
• এজেন্ট রানটাইম ডেপ্লয়মেন্ট গাইড