১. ভূমিকা
এই কোডল্যাবে, আপনি গুগল ক্লাউডে চলমান এআই এজেন্ট ডিবাগ করা শিখবেন। আপনি এজেন্ট রানটাইমে একটি সিমুলেটর এজেন্ট ডেপ্লয় করবেন, সমস্যা শনাক্ত করতে ক্লাউড অবজার্ভেবিলিটি ব্যবহার করবেন এবং রিয়েল টাইমে ত্রুটির মূল কারণ খুঁজে বের করে তা সমাধান করতে জেমিনি ক্লাউড অ্যাসিস্ট ও অ্যান্টিগ্র্যাভিটি আইডিই ব্যবহার করবেন।
এই ডেমোর মূল ভিত্তি হলো, আমরা এইমাত্র সিমুলেটর এজেন্টে ADK EventCompaction যুক্ত করেছি। এটি সিমুলেটরকে জেমিনি (Gemini) ব্যবহার করে পর্যায়ক্রমে তার ওয়ার্কফ্লোর সারসংক্ষেপ করতে দেয়, যা প্রতিটি ধাপে মডেলে পাঠানো মোট কনটেক্সট কমিয়ে দেয় – ফলে প্রতিক্রিয়ার মান উন্নত হয় এবং মোট খরচ কমে আসে। কিন্তু, আমরা জানতে পারব যে আমাদের EventCompactionConfig-এ একটি বাগ রয়েছে, যা এজেন্টে ত্রুটি সৃষ্টি করছে! এই কোডল্যাবে দেখানো হয়েছে কীভাবে আমরা এই ধরনের সমস্যা খুঁজে বের করব এবং দ্রুত সমাধান করব।
আপনি যা করবেন
- ম্যারাথন সিমুলেটর এজেন্টটিকে এজেন্ট রানটাইমে স্থাপন করুন।
- এজেন্টের ত্রুটি শনাক্ত করতে একটি ক্লাউড মনিটরিং অ্যালার্ট সেট আপ করুন।
- Cloud Trace এবং Gemini Cloud Assist ব্যবহার করে ত্রুটিগুলো তদন্ত করুন।
- Antigravity এবং MCP ব্যবহার করে এজেন্টটির মূল কারণ খুঁজে বের করুন এবং প্যাচ করুন।
আপনার যা যা লাগবে
- ক্রোমের মতো একটি ওয়েব ব্রাউজার।
- একটি গুগল অ্যাকাউন্ট
- অ্যান্টিগ্র্যাভিটি (ম্যাক, লিনাক্স এবং উইন্ডোজ সমর্থন করে)
- পাইথন ৩.১৩+ ।
- uv (পাইথন প্যাকেজ ম্যানেজার)
আনুমানিক সময়কাল: ৪৫ মিনিট
আনুমানিক খরচ: ৫ মার্কিন ডলারের কম
২. শুরু করার আগে
একটি গুগল ক্লাউড প্রজেক্ট তৈরি করুন
- গুগল ক্লাউড কনসোলে , একটি গুগল ক্লাউড প্রজেক্ট নির্বাচন করুন বা তৈরি করুন ।
- আপনার ক্লাউড প্রজেক্টের জন্য বিলিং চালু আছে কিনা তা নিশ্চিত করুন।
আপনার পরিবেশ তৈরি করুন
Antigravity খুলুন এবং সাইন ইন করুন। এরপর, cmd-shift-P (অথবা ctrl-shift-P ) চেপে ধরে "Create New Terminal" টাইপ করে একটি টার্মিনাল খুলুন।
- টার্মিনাল থেকে গুগল ক্লাউডের মাধ্যমে প্রমাণীকরণ করুন:
gcloud auth login
gcloud auth application-default login
- আপনার প্রজেক্ট আইডি সেট করুন:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID
এপিআই সক্ষম করুন
প্রয়োজনীয় গুগল ক্লাউড এপিআইগুলো সক্রিয় করতে নিম্নলিখিত কমান্ডটি চালান:
gcloud services enable \
aiplatform.googleapis.com \
logging.googleapis.com \
apphub.googleapis.com \
cloudtrace.googleapis.com \
telemetry.googleapis.com
gcloud services enable \
geminicloudassist.googleapis.com \
cloudaicompanion.googleapis.com
৩. সিমুলেটর এজেন্ট সেট আপ করুন
এই ধাপে, আপনি ডেমো রিপোজিটরি ক্লোন করবেন এবং সিমুলেটর এজেন্টের জন্য এনভায়রনমেন্ট ভেরিয়েবল কনফিগার করবেন।
রিপোজিটরি ক্লোন করুন
next-26-keynotes রিপোজিটরিটি ক্লোন করুন এবং demo ডিরেক্টরিতে যান:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents
পরিবেশ ভেরিয়েবল কনফিগার করুন
সিমুলেটর এজেন্ট কনফিগারেশনের জন্য একটি .env ফাইল ব্যবহার করে।
অ্যান্টিগ্র্যাভিটি উইন্ডোর (এক্সপ্লোরার) বাম দিকে sample.env ফাইলটি খুঁজুন:
sample.env খুলুন এবং GCP_PROJECT_ID ফিল্ডটি আপনার আসল Google Cloud Project ID দিয়ে আপডেট করুন। ফাইলটি দেখতে অনেকটা এইরকম হবে:
GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false
৪. সিমুলেটর এজেন্টকে এজেন্ট রানটাইমে স্থাপন করুন
এখন, আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে এজেন্ট রানটাইমে এজেন্টটি স্থাপন করবেন।
নির্ভরতা ইনস্টল করুন
uv sync
এজেন্ট রানটাইমে স্থাপন করুন
-
adk deployকমান্ডটি চালান। এই ধাপে আপনার এজেন্টকে প্যাকেজ করে গুগল ক্লাউডে (এজেন্ট রানটাইম) স্থাপন করা হয়।
uv run adk deploy agent_engine \
--project="$PROJECT_ID" \
--region="us-central1" \
--otel_to_cloud \
--env_file="sample.env" \
--adk_app_object=app \
simulator_agent
এটি চলতে ৫ মিনিট পর্যন্ত সময় লাগতে পারে। অবশেষে আপনি এইরকম একটি আউটপুট দেখতে পাবেন:
✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...
- একটি ওয়েব ব্রাউজার থেকে এজেন্ট রানটাইম কনসোলটি খুলুন। আপনি এজেন্ট রানটাইমে
simulator_agentচলতে দেখবেন, যার টেলিমেট্রি সংগ্রহ সক্রিয় করা আছে ।
৫. একটি সতর্কতা নীতি নির্ধারণ করুন।
এজেন্ট রানটাইম ত্রুটি স্বয়ংক্রিয়ভাবে শনাক্ত করতে, আপনাকে গুগল ক্লাউড কনসোলে একটি লগ-ভিত্তিক অ্যালার্ট তৈরি করতে হবে।
- ক্লাউড মনিটরিং - অ্যালার্টিং কনসোলে যান।
- ‘এডিট নোটিফিকেশন চ্যানেল’-এ ক্লিক করুন। নিচে স্ক্রল করে ‘ইমেল টাইপ’-এ যান, তারপর আপনার ব্যক্তিগত ইমেলে পাঠানোর জন্য একটি ইমেল নোটিফিকেশন চ্যানেল তৈরি করুন। ‘সেভ’- এ ক্লিক করুন।
- অ্যালার্টিং ড্যাশবোর্ডে ফিরে যান এবং 'Create Policy'-তে ক্লিক করুন।
- স্ক্রিনের ডানদিকে, 'Create log-based alert'-এ ক্লিক করুন।
- আপনাকে লগ এক্সপ্লোরার -এ পুনঃনির্দেশিত করা হবে। নিম্নলিখিত লগ কোয়েরিটি পেস্ট করুন, যেখানে আপনার প্রজেক্ট আইডি দিয়ে প্রতিস্থাপন করতে হবে।
resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"
- রান কোয়েরি-তে ক্লিক করুন। আপনি এখনও কোনো লগ দেখতে পাবেন না - এটাই স্বাভাবিক।
- ফলাফল টুলবারে থাকা অ্যাকশনস- এ ক্লিক করুন, তারপর ক্রিয়েট লগ অ্যালার্ট-এ ক্লিক করুন।
- লগ-ভিত্তিক অ্যালার্টটি কনফিগার করুন। অ্যালার্টটির একটি নাম দিন (যেকোনো), তারপর তীব্রতার স্তরটি 'Error'- এ সেট করুন।
- 'বিজ্ঞপ্তির ফ্রিকোয়েন্সি সেট করুন' বিভাগের জন্য পরবর্তী ধাপে যান (ডিফল্ট মান অপরিবর্তিত রাখুন)।
- ‘কাকে জানানো হবে?’- এর জন্য, অ্যালার্টটি এমনভাবে সেট করুন যাতে এটি আপনার সদ্য সেট আপ করা ইমেল নোটিফিকেশন চ্যানেলটি (যেমন:
My Email) ট্রিগার করে। - সংরক্ষণ করুন-এ ক্লিক করুন।
৬. ঘটনাটি ঘটান
এখন যেহেতু এজেন্টটি স্থাপন ও পর্যবেক্ষণ করা হচ্ছে, চলুন ম্যারাথন সিমুলেশনটি এমনভাবে চালু করার চেষ্টা করি যাতে একটি ত্রুটি দেখা দেয়।
- গুগল ক্লাউড কনসোলে, এজেন্ট রানটাইম কনসোলে যান।
-
simulator_agentক্লিক করুন। - উপরের টুলবার থেকে প্লেগ্রাউন্ড-এ ক্লিক করুন। এটি ADK এজেন্টের সাথে একটি নতুন সেশন শুরু করবে।
- সেশন চ্যাট উইন্ডো থেকে,
Test Simulationটাইপ করুন এবং প্রম্পটটি পাঠাতে এন্টার চাপুন।
এটি ম্যারাথন সিমুলেশনটি চালু করবে, যা পরিকল্পিত পথ ধরে হাজার হাজার সিমুলেটেড দৌড়বিদকে ট্র্যাক করবে। যেহেতু সিমুলেশনটি দৌড়ের একাধিক "জোন" মূল্যায়ন করবে, তাই আপনি get_runner_telemetry এবং analyze_medical_risk টুলগুলোর একাধিক কল দেখতে পাবেন।
- মিনিটখানেকের মধ্যেই আপনার ইনবক্সে একটি ইমেল এসে পৌঁছাবে, যা এজেন্টের মধ্যে একটি নতুন ইনসিডেন্ট সম্পর্কে আপনাকে সতর্ক করবে।
ক্লাউড মনিটরিং কনসোল খুলতে 'ভিউ ইনসিডেন্ট'-এ ক্লিক করুন। কনসোলের মধ্যে সমস্যাটি অনুসন্ধান করতে পরবর্তী পৃষ্ঠায় যান।
৭. কনসোলে ঘটনাটি তদন্ত করুন
- ক্লাউড মনিটরিং কনসোলে ইনসিডেন্টটি দেখুন। আপনি সিমুলেটর এজেন্ট থেকে আসা এরর লগ দেখতে পাবেন।
এই দৃষ্টিকোণ থেকে এজেন্টটি ঠিক কোন পর্যায়ে ব্যর্থ হয়েছে তা স্পষ্টভাবে দেখা কঠিন। এজেন্টের অন্তর্নিহিত টুল কল এবং যুক্তির প্রবাহ দেখতে, আমরা এজেন্টের ট্রেসগুলো পরীক্ষা করব।
- এজেন্ট রানটাইম কনসোলটি আবার খুলুন। simulator_agent-এ ক্লিক করুন, তারপর Traces ট্যাবটি খুলুন।
- তালিকা থেকে সবচেয়ে সাম্প্রতিক ট্রেসটিতে ক্লিক করুন। এরপর উপরের ডানদিকে, টাইমলাইন-এ ক্লিক করুন। আপনি স্বতন্ত্র 'স্প্যান' সহ একটি ট্রেস ভিউ দেখতে পাবেন। একটি স্প্যান এজেন্টের ওয়ার্কফ্লো-এর মধ্যে একটি মডেল বা টুল কলকে প্রতিনিধিত্ব করে।
- ট্রেস ভিউতে থাকা শেষ স্প্যানটিতে ক্লিক করুন। এটি লাল রঙের হওয়া উচিত।
- স্ট্যাকট্রেস-এ ক্লিক করুন। আপনি একটি জেমিনি এপিআই মডেল কল সম্পর্কিত ত্রুটির লগ দেখতে পাবেন। বিশেষত, একটি
400: Invalid Argumentত্রুটি। এটি সিমুলেটর এজেন্ট কর্তৃক জেমিনি এপিআই-তে পাঠানো পেলোডের সাথে সম্পর্কিত একটি অনুরোধ-স্তরের সমস্যার ইঙ্গিত দেয়।
৮. [ঐচ্ছিক] ডিবাগ করার জন্য ক্লাউড অ্যাসিস্ট ইনভেস্টিগেশনস ব্যবহার করুন।
- ব্যর্থ হওয়া স্প্যানটির মধ্যে, 'লগস অ্যান্ড ইভেন্টস'- এ ক্লিক করুন। এর পাশে থাকা ঝিকিমিকি বোতামসহ 'এক্সেপশন' লগটি খুঁজুন। তারপর, 'ইনভেস্টিগেট লগ'-এ ক্লিক করুন।
- এটি স্ক্রিনের ডানদিকের সাইডবার থেকে একটি ক্লাউড অ্যাসিস্ট ইনভেস্টিগেশন শুরু করে। এটি লোড হতে প্রায় ৩-৫ মিনিট সময় লাগবে।
- একবার সম্পন্ন হলে, তদন্তটি চালু করুন।
- তদন্তের সারসংক্ষেপ দেখুন।
- নিচে স্ক্রল করুন এবং হাইপোথিসিসগুলো দেখুন। জেমিনি ক্লাউড অ্যাসিস্টের সিমুলেটর এজেন্টের
agent.pyফাইলের সেই নির্দিষ্ট লাইনটি শনাক্ত করার কথা, যেটি জেমিনি এপিআই 400 এররটি দিচ্ছে।
চলুন আমাদের এজেন্টের সোর্স কোড খুলে আরও গভীরে যাই এবং সমস্যাটির মূল কারণ খুঁজে বের করতে অ্যান্টিগ্র্যাভিটি ব্যবহার করি। পরবর্তী পৃষ্ঠায় যান।
৯. সমস্যার মূল কারণ খুঁজে বের করতে এবং সমাধান করতে অ্যান্টিগ্র্যাভিটি ব্যবহার করুন।
- অ্যান্টিগ্র্যাভিটি পুনরায় চালু করুন।
- স্ক্রিনের উপরের ডানদিকে এজেন্ট ম্যানেজার খুলুন।
- মডেলটি জেমিনি ৩ ফ্ল্যাশ এবং প্ল্যানিং মোডে সেট করা আছে কিনা তা নিশ্চিত করুন।
- নিম্নলিখিত নির্দেশটি প্রবেশ করান এবং এন্টার চাপুন।
Why is the Simulator Agent failing to run in Agent Engine?
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues - including issues that have been closed.
For instance, you could query: is:issue eventscompactionconfig does not trigger summarization
Also look closely at the EventsCompactionConfig in agent.py.
আপনার Antigravity-কে agent.py এর কোড পরীক্ষা করতে এবং GitHub-এ প্রাসঙ্গিক সমস্যাগুলো খুঁজতে দেখা উচিত:
জেমিনি এপিআই 400 ত্রুটির মূল কারণ হলো আমরা জেমিনি 3 ফ্ল্যাশের প্রায় ১০ লক্ষ ইনপুট কনটেক্সট টোকেন সীমা অতিক্রম করছি। এর কারণ হলো , সিমুলেটর এজেন্ট টুল-কলগুলো থেকে আসা বিশাল প্রতিক্রিয়াগুলোকে কার্যকরভাবে সংক্ষিপ্ত করার জন্য আমরা যথেষ্ট ঘন ঘন ইভেন্টকমপ্যাকশন ট্রিগার করছি না।
এর সমাধানে, অ্যান্টিগ্র্যাভিটির উচিত EventsCompactionConfig এ একটি token_threshold প্যারামিটার যোগ করার পরামর্শ দেওয়া, যাতে একটি নির্দিষ্ট সংখ্যক টোকেনে পৌঁছানোর পর প্রতিটি আহ্বানের মধ্যে পর্যায়ক্রমে কনটেক্সটটি সংকুচিত করা যায়।
এটি এই গিটহাব ইস্যুটিতে প্রস্তাবিত সমাধানের সাথে সামঞ্জস্যপূর্ণ।
agent.py.
নিশ্চিত করুন যে আপনি এর মতো কিছু দেখতে পাচ্ছেন:
app = App(
name="simulator_agent",
root_agent=root_agent,
events_compaction_config=EventsCompactionConfig(
compaction_interval=3,
overlap_size=1,
summarizer=summarizer,
token_threshold=200000,
event_retention_size=2,
),
)
১০. সমাধানটি পুনরায় প্রয়োগ এবং যাচাই করুন
এখন যেহেতু আমরা ADK এজেন্টের EventCompactionConfig এ token_threshold ফিক্সটি প্রয়োগ করেছি, আমরা সিমুলেটর এজেন্টকে এজেন্ট রানটাইমে পুনরায় ডেপ্লয় করতে পারি।
- অ্যান্টিগ্র্যাভিটি খুলুন –> নতুন টার্মিনাল ।
- এনভায়রনমেন্ট ভেরিয়েবল সেট করুন।
AGENT_RUNTIME_IDহবে আপনারsimulator_agentএর সম্পূর্ণ রিসোর্স নেম । এটি এজেন্ট রানটাইম কনসোলের এজেন্ট লিস্টে পাওয়া যাবে।
export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"
- এজেন্টকে পুনরায় মোতায়েন করুন:
uv run adk deploy agent_engine \
--project="$PROJECT_ID" \
--region="us-central1" \
--otel_to_cloud \
--agent_engine_id="$AGENT_RUNTIME_ID" \
--env_file="sample.env" \
--adk_app_object=app \
simulator_agent
এটি চলতে কয়েক মিনিট সময় লাগবে। সফল হলে, আপনি দেখতে পাবেন:
✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...
- এজেন্ট রানটাইম কনসোল খুলুন।
simulator_agentপুনরায় খুলুন। প্লেগ্রাউন্ডে ক্লিক করুন। - একই প্রম্পটটি লিখুন:
Test Simulation- তারপর, এন্টার চাপুন। - সম্পূর্ণ ব্যাকএন্ড ম্যারাথন সিমুলেশনটি চলতে কয়েক মিনিট সময় লাগবে। আপনি একাধিক টুল কল দেখতে পাবেন। অবশেষে, আপনি এই ধরনের একটি প্রতিক্রিয়া দেখতে পাবেন:
এর মানে হলো সিমুলেটরটি সফলভাবে চলেছে! ✅
- ওই ADK সেশনের জন্য ট্রেস ভিউটি খুলুন।
- আপনার সব "নীল" স্প্যান দেখা উচিত, কোনো লাল ত্রুটি থাকবে না। লক্ষ্য করুন, সেশনগুলোর মোট টোকেন সংখ্যা জেমিনি এপিআই-এর ১০ লক্ষ কনটেক্সট টোকেন সীমা অতিক্রম করেছে। এটা ঠিক আছে, কারণ এখন প্রতিটি আহ্বানের মধ্যেই
EventCompactionযথেষ্ট ঘন ঘন চলছে, যার ফলে স্বতন্ত্র মডেল কলগুলোর জন্য সামগ্রিক কনটেক্সট সীমা অতিক্রম করার সম্ভাবনা থাকছে না।
🎊 হুররে! আমরা সিমুলেটর এজেন্টের ত্রুটিটি সমাধান করেছি!
১১. পরিষ্কার করুন
আপনার গুগল ক্লাউড অ্যাকাউন্টে চার্জ হওয়া এড়াতে, এই কোডল্যাব চলাকালীন তৈরি করা রিসোর্সগুলো মুছে ফেলুন।
এজেন্ট রানটাইম অ্যাপটি মুছে ফেলুন
আপনি কনসোলের মাধ্যমে অথবা gcloud কমান্ড ব্যবহার করে (যদি আপনার কাছে রিসোর্সের নামটি থাকে) রিজনিং ইঞ্জিন ইনস্ট্যান্সটি ডিলিট করতে পারেন। সরলতার জন্য, কনসোল ব্যবহার করুন:
- এজেন্ট রানটাইম পৃষ্ঠায় যান।
-
simulator_agentনির্বাচন করুন –> ডান পাশের ট্রিপল-ডট বোতামে ক্লিক করুন। - ডিলিট-এ ক্লিক করুন।
ক্লাউড মনিটরিং পলিসি মুছে ফেলুন
- ক্লাউড মনিটরিং কনসোল -> অ্যালার্টিং- এ যান।
- নিচে স্ক্রল করে Policies- এ যান, তারপর পলিসিটি ডিলিট করতে ট্রিপল-ডট বাটনে ক্লিক করুন।
১২. 🎊 অভিনন্দন!
অভিনন্দন! আপনি এইমাত্র গুগল ক্লাউডে একটি এআই এজেন্ট সফলভাবে ডিবাগ করেছেন।
আপনি যা শিখেছেন
- এজেন্ট রানটাইমে কীভাবে এজেন্ট স্থাপন করতে হয়।
- ক্লাউড মনিটরিং অ্যালার্ট ব্যবহার করে কীভাবে ত্রুটি শনাক্ত করা যায়।
- ক্লাউড লগিং এবং এজেন্ট রানটাইমের ট্রেস ভিউ ব্যবহার করে কীভাবে সক্রিয় ইনসিডেন্টগুলি অন্বেষণ করবেন।
- Gemini Cloud Assist ব্যবহার করে ব্যর্থতাগুলো কীভাবে তদন্ত করবেন।
- এজেন্ট বাগের মূল কারণ খুঁজে বের করতে এবং তা সমাধান করতে অ্যান্টিগ্র্যাভিটি কীভাবে ব্যবহার করবেন।
- দীর্ঘস্থায়ী ও টুল-নির্ভর এজেন্ট টার্নগুলো সামলানোর জন্য ADK ইভেন্ট কম্প্যাকশনকে কীভাবে সূক্ষ্মভাবে সমন্বয় করা যায়
পরবর্তী পদক্ষেপ
- এজেন্ট রানটাইম সম্পর্কে আরও জানুন।
- এজেন্ট ডেভেলপমেন্ট কিট সম্পর্কে আরও জানুন।
- ক্লাউড মনিটরিং-এ অ্যালার্টিং সম্পর্কে আরও জানুন।
- জেমিনি ক্লাউড অ্যাসিস্ট সম্পর্কে আরও জানুন।