১. ভূমিকা
এই কোডল্যাবে, আপনি ADK ব্যবহার করে একটি এজেন্ট তৈরি করবেন যা Gemini 3.1 Pro দ্বারা চালিত হবে। এজেন্টটি দুটি রিমোট (গুগল-হোস্টেড) MCP সার্ভারের টুলস দ্বারা সজ্জিত থাকবে, যা জনসংখ্যাতাত্ত্বিক, মূল্য নির্ধারণ এবং বিক্রয় ডেটার জন্য BigQuery এবং বাস্তব-জগতের অবস্থান বিশ্লেষণ ও যাচাইকরণের জন্য Google Maps নিরাপদে অ্যাক্সেস করতে পারবে।
এজেন্টটি কাল্পনিক বেকারি ডেটাসেট সম্পর্কিত ব্যবসায়িক সমস্যা সমাধানের জন্য ব্যবহারকারী এবং গুগল ক্লাউড পরিষেবাগুলোর মধ্যে অনুরোধগুলো সমন্বয় করে।
আপনি যা করবেন
- ডেটা প্রস্তুত করুন: BigQuery-তে বেকারির ভিত্তিগত ডেটাসেটটি তৈরি করুন।
- এজেন্ট তৈরি করুন: এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে একটি বুদ্ধিমান এজেন্ট তৈরি করুন।
- টুল একীভূতকরণ: MCP সার্ভারের মাধ্যমে এজেন্টকে BigQuery এবং Maps-এর কার্যকারিতা দিয়ে সজ্জিত করুন।
- বাজার বিশ্লেষণ করুন: বাজারের প্রবণতা এবং সম্পৃক্ততা মূল্যায়ন করতে এজেন্টের সাথে আলোচনা করুন।
আপনার যা যা লাগবে
- ক্রোমের মতো একটি ওয়েব ব্রাউজার
- বিলিং চালু থাকা একটি গুগল ক্লাউড প্রজেক্ট অথবা একটি জিমেইল অ্যাকাউন্ট।
এই কোডল্যাবটি নতুনদের সহ সকল স্তরের ডেভেলপারদের জন্য। আপনি ADK ডেভেলপমেন্টের জন্য গুগল ক্লাউড শেল-এর কমান্ড-লাইন ইন্টারফেস এবং পাইথন কোড ব্যবহার করবেন। আপনাকে পাইথন বিশেষজ্ঞ হতে হবে না, তবে কোড কীভাবে পড়তে হয় সে সম্পর্কে প্রাথমিক ধারণা থাকলে বিষয়গুলো বুঝতে সুবিধা হবে।
২. শুরু করার আগে
একটি গুগল ক্লাউড প্রজেক্ট তৈরি করুন
- গুগল ক্লাউড কনসোলের প্রজেক্ট সিলেক্টর পেজে, একটি গুগল ক্লাউড প্রজেক্ট নির্বাচন করুন বা তৈরি করুন ।
- আপনার ক্লাউড প্রোজেক্টের জন্য বিলিং চালু আছে কিনা তা নিশ্চিত করুন। কোনো প্রোজেক্টে বিলিং চালু আছে কিনা তা কীভাবে পরীক্ষা করবেন, তা জেনে নিন।
ক্লাউড শেল শুরু করুন
ক্লাউড শেল হলো গুগল ক্লাউডে চালিত একটি কমান্ড-লাইন পরিবেশ, যা প্রয়োজনীয় টুলস সহ আগে থেকেই লোড করা থাকে।
- Google Cloud কনসোলের শীর্ষে থাকা Activate Cloud Shell-এ ক্লিক করুন:
- ক্লাউড শেলে সংযুক্ত হওয়ার পর, আপনার প্রমাণীকরণ যাচাই করতে এই কমান্ডটি চালান:
gcloud auth list
- আপনার প্রজেক্টটি gcloud-এর সাথে ব্যবহারের জন্য কনফিগার করা হয়েছে কিনা তা নিশ্চিত করতে নিম্নলিখিত কমান্ডটি চালান:
gcloud config get project
- প্রকল্পটি প্রত্যাশা অনুযায়ী আছে কিনা তা নিশ্চিত করুন, এবং তারপর আপনার প্রজেক্ট আইডি সেট করতে নিচের কমান্ডটি চালান:
export PROJECT_ID=$(gcloud config get project)
৩. কোডটি সংগ্রহ করুন
রিপোজিটরি ক্লোন করুন
- রিপোজিটরিটি আপনার ক্লাউড শেল এনভায়রনমেন্টে ক্লোন করুন:
git clone https://github.com/google/mcp.git
- ডেমো ডিরেক্টরিতে যান:
cd mcp/examples/launchmybakery
প্রমাণীকরণ করুন
আপনার গুগল ক্লাউড অ্যাকাউন্ট দিয়ে প্রমাণীকরণের জন্য নিম্নলিখিত কমান্ডটি চালান। ADK-এর BigQuery অ্যাক্সেস করার জন্য এটি আবশ্যক।
gcloud auth application-default login
প্রমাণীকরণ প্রক্রিয়াটি সম্পন্ন করতে নির্দেশাবলী অনুসরণ করুন।
৪. পরিবেশ এবং BigQuery কনফিগার করুন
সেটআপ স্ক্রিপ্ট চালান
- এনভায়রনমেন্ট সেটআপ স্ক্রিপ্টটি চালান। এই স্ক্রিপ্টটি BigQuery এবং Google Maps API সক্রিয় করে এবং আপনার প্রজেক্ট আইডি ও ম্যাপস এপিআই কী সহ একটি
.envফাইল তৈরি করে।
chmod +x setup/setup_env.sh
./setup/setup_env.sh
- BigQuery সেটআপ স্ক্রিপ্টটি চালান। এই স্ক্রিপ্টটি ক্লাউড স্টোরেজ বাকেট তৈরি করা, ডেটা আপলোড করা এবং BigQuery ডেটাসেট ও টেবিলগুলো প্রস্তুত করার কাজগুলো স্বয়ংক্রিয়ভাবে করে।
chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh
স্ক্রিপ্টটি সম্পন্ন হলে, mcp_bakery ডেটাসেটটি তৈরি হবে এবং নিম্নলিখিত টেবিলগুলো দিয়ে তা পূর্ণ হবে:
- জনসংখ্যাতাত্ত্বিক তথ্য - আদমশুমারির উপাত্ত এবং জিপ কোড অনুযায়ী জনসংখ্যার বৈশিষ্ট্য।
- বেকারির দাম - বিভিন্ন বেকড পণ্যের প্রতিযোগী মূল্য এবং পণ্যের বিবরণ।
- sales_history_weekly - স্টোর এবং পণ্য অনুযায়ী সাপ্তাহিক বিক্রয় কর্মক্ষমতা (পরিমাণ এবং রাজস্ব)।
- foot_traffic - জিপ কোড এবং দিনের সময় অনুযায়ী আনুমানিক পথচারী চলাচলের স্কোর।
- আপনার গুগল ক্লাউড প্রজেক্টের BigQuery কনসোলে গিয়ে ডেটাসেট এবং টেবিলগুলো তৈরি হয়েছে কিনা তা যাচাই করুন:
৫. ADK ইনস্টল করুন
এখন যেহেতু পরিকাঠামো প্রস্তুত, চলুন একটি ভার্চুয়াল পাইথন এনভায়রনমেন্ট তৈরি করি এবং ADK-এর জন্য প্রয়োজনীয় প্যাকেজগুলো ইনস্টল করি।
- একটি ভার্চুয়াল পরিবেশ তৈরি করুন:
python3 -m venv .venv
- ভার্চুয়াল পরিবেশ সক্রিয় করুন:
source .venv/bin/activate
- ADK ইনস্টল করুন:
pip install google-adk==1.28.0
- এজেন্ট ডিরেক্টরিতে যান:
cd adk_agent/
৬. ADK অ্যাপ্লিকেশনটি পরিদর্শন করুন।
Cloud Shell Editor খুলতে এবং mcp/examples/launchmybakery ডিরেক্টরির অধীনে ক্লোন করা রিপোজিটরিটি দেখতে, Cloud Shell-এর Open Editor বোতামটি ক্লিক করুন।
এজেন্ট কোডটি ইতিমধ্যেই adk_agent/ ডিরেক্টরিতে দেওয়া আছে। চলুন সলিউশনের কাঠামোটি অন্বেষণ করা যাক:
launchmybakery/
├── data/ # Pre-generated CSV files for BigQuery
├── adk_agent/ # AI Agent Application (ADK)
│ └── mcp_bakery_app/ # App directory
│ ├── agent.py # Agent definition
│ ├── tools.py # Custom tools for the agent
│ └── .env # Project configuration (created by setup script)
├── setup/ # Infrastructure setup scripts
└── cleanup/ # Infrastructure cleanup scripts
mcp_bakery_app এর মূল ফাইলগুলো:
-
agent.py: এজেন্ট, এর টুলস এবং মডেল নির্ধারণকারী মূল লজিক (Gemini 3.1 Pro Preview)। -
tools.py: এতে যেকোনো কাস্টম টুলের সংজ্ঞা থাকে। -
.env: এতে আপনার প্রোজেক্ট কনফিগারেশন এবং সেটআপ স্ক্রিপ্ট দ্বারা তৈরি গোপনীয় তথ্য (যেমন এপিআই কী) থাকে।
১. এমসিপি টুলসেট প্রারম্ভিককরণ:
এখন, MCP টুলসেটগুলো কীভাবে ইনিশিয়ালাইজ করা হয় তা বোঝার জন্য এডিটরে adk_agent/mcp_bakery_app/tools.py খুলুন।
আমাদের এজেন্টকে BigQuery এবং Google Maps-এর সাথে যোগাযোগ করতে সক্ষম করার জন্য, মডেল কনটেক্সট প্রোটোকল (MCP) ক্লায়েন্ট কনফিগার করতে হবে।
এই কোডটি StreamableHTTPConnectionParams ব্যবহার করে গুগলের দূরবর্তী MCP সার্ভারগুলোর সাথে সুরক্ষিত সংযোগ স্থাপন করে।
def get_maps_mcp_toolset():
dotenv.load_dotenv()
maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=MAPS_MCP_URL,
headers={
"X-Goog-Api-Key": maps_api_key
}
)
)
print("MCP Toolset configured for Streamable HTTP connection.")
return tools
def get_bigquery_mcp_toolset():
credentials, project_id = google.auth.default(
scopes=["https://www.googleapis.com/auth/bigquery"]
)
credentials.refresh(google.auth.transport.requests.Request())
oauth_token = credentials.token
HEADERS_WITH_OAUTH = {
"Authorization": f"Bearer {oauth_token}",
"x-goog-user-project": project_id
}
tools = MCPToolset(
connection_params=StreamableHTTPConnectionParams(
url=BIGQUERY_MCP_URL,
headers=HEADERS_WITH_OAUTH
)
)
print("MCP Toolset configured for Streamable HTTP connection.")
return tools
- ম্যাপস টুলসেট: আপনার এপিআই কী ব্যবহার করে ম্যাপস এমসিপি সার্ভারের সাথে সংযোগ স্থাপন করে।
- BigQuery টুলসেট: এই ফাংশনটি BigQuery MCP সার্ভারের সাথে সংযোগ স্থাপন করে। এটি google.auth ব্যবহার করে স্বয়ংক্রিয়ভাবে আপনার ক্লাউড ক্রেডেনশিয়াল সংগ্রহ করে, একটি OAuth Bearer টোকেন তৈরি করে এবং সেটিকে Authorization হেডারে যুক্ত করে।
২. এজেন্টের সংজ্ঞা:
এখন, এজেন্টটি কীভাবে সংজ্ঞায়িত করা হয়েছে তা দেখতে এডিটরে adk_agent/mcp_bakery_app/agent.py খুলুন।
LlmAgent টি gemini-3.1-pro-preview মডেল দিয়ে ইনিশিয়ালাইজ করা হয়েছে।
maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()
root_agent = LlmAgent(
model='gemini-3.1-pro-preview',
name='root_agent',
instruction=f"""
Help the user answer questions by strategically combining insights from two sources:
1. **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the mcp_bakery dataset. Do not use any other dataset.
Run all query jobs from project id: {project_id}.
2. **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
Include a hyperlink to an interactive map in your response where appropriate.
""",
tools=[maps_toolset, bigquery_toolset]
)
- সিস্টেম নির্দেশাবলী: এজেন্টকে BigQuery (ডেটার জন্য) এবং Maps (অবস্থান বিশ্লেষণের জন্য) উভয় থেকে প্রাপ্ত তথ্য একত্রিত করার জন্য নির্দিষ্ট নির্দেশাবলী দেওয়া হয়।
- টুলস: এজেন্টকে
maps_toolsetএবংbigquery_toolsetউভয়ই বরাদ্দ করা হয়েছে, যার ফলে এটি উভয় সার্ভিসের সক্ষমতা ব্যবহার করতে পারে।
এজেন্টটি রিপো-তে সংজ্ঞায়িত নির্দেশাবলী এবং টুলস মেনে চলে। এজেন্টের আচরণে এর প্রভাব দেখতে আপনি নির্দ্বিধায় নির্দেশাবলীতে পরিবর্তন করতে পারেন।
৭. আপনার এজেন্টের সাথে কথা বলুন!
ক্লাউড শেলের টার্মিনালে ফিরে যান এবং adk_agent ডিরেক্টরিতে যাওয়ার জন্য এই কমান্ডটি চালান (যদি আপনি ইতিমধ্যে এটি না করে থাকেন):
cd adk_agent/
ADK ওয়েব ইন্টারফেস শুরু করতে নিম্নলিখিত কমান্ডটি চালান। এই কমান্ডটি চ্যাট অ্যাপ্লিকেশনটি হোস্ট করার জন্য একটি লাইটওয়েট ওয়েব সার্ভার চালু করে:
adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'
সার্ভারটি চালু হয়ে গেলে, আপনি ক্লাউড শেলে নিম্নলিখিত বিষয়গুলো দেখতে পাবেন:
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://127.0.0.1:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
ADK UI অ্যাক্সেস করার জন্য আপনার কাছে দুটি বিকল্প রয়েছে:
বিকল্প ১: স্থানীয় লিঙ্কে ক্লিক করুন। আপনার ক্লাউড শেল টার্মিনালে প্রদর্শিত http://127.0.0.1:8000 লিঙ্কে ক্লিক করুন।
বিকল্প ২: ওয়েব প্রিভিউ ব্যবহার করুন
- ক্লাউড শেলের উপরের ডান কোণায় থাকা ওয়েব প্রিভিউ বাটনটিতে ক্লিক করুন।
- পোর্ট পরিবর্তন নির্বাচন করুন।
- পোর্ট নম্বর হিসেবে 8000 প্রবেশ করান এবং 'Change and Preview'-এ ক্লিক করুন।
ওয়েব UI-তে নিম্নলিখিত প্রশ্নগুলো জিজ্ঞাসা করে এজেন্টের সাথে যোগাযোগ করুন । আপনি দেখবেন প্রাসঙ্গিক টুলগুলো চালু হচ্ছে।
- এলাকাটি খুঁজুন (ম্যাক্রো): "আমি লস অ্যাঞ্জেলেসে একটি বেকারি খুলতে চাই। সর্বোচ্চ সকালের পথচারী চলাচলের স্কোরযুক্ত জিপ কোডটি খুঁজুন।"
এজেন্টকে BigQuery-তে foot_traffic টেবিলটি কোয়েরি করার জন্য get_table_info এবং execute_sql মতো টুল ব্যবহার করতে হবে।
- অবস্থান যাচাই করুন (মাইক্রো): "আপনি কি ঐ জিপ কোডে 'বেকারি' খুঁজে দেখতে পারেন যে সেখানে এর ব্যাপক চাহিদা আছে কিনা?"
এই প্রশ্নের উত্তর দেওয়ার জন্য এজেন্টকে ম্যাপস টুলসেটের search places টুলগুলো ব্যবহার করতে হবে।
চেষ্টা করে দেখুন! আপনার ADK এজেন্টকে কীভাবে কাজ করতে দেখা যায়, তা জানতে এই নমুনা প্রশ্নগুলো দেখুন:
- আমি লস অ্যাঞ্জেলেসে আমার চতুর্থ বেকারি খুলতে চাই। আমার এমন একটি এলাকা দরকার যেখানে খুব সকালে লোকজনের আনাগোনা বেশি থাকে। সবচেয়ে বেশি 'সকালের' পথচারী চলাচল স্কোরযুক্ত জিপ কোডটি খুঁজে বের করুন।
- আপনি কি ওই জিপ কোডে 'বেকারি' খুঁজে দেখতে পারেন যে সেখানে ভিড় বেশি কিনা? যদি অনেক বেশি থাকে, তাহলে 'স্পেশালিটি কফি'র দোকানগুলো দেখুন, যাতে আমি সেগুলোর কাছাকাছি জায়গা নিয়ে পথচারীদের আনাগোনা ধরতে পারি।
- আচ্ছা, আমি এটাকে একটি প্রিমিয়াম ব্র্যান্ড হিসেবে প্রতিষ্ঠা করতে চাই। লস অ্যাঞ্জেলেস মেট্রো এলাকায় একটি 'সাওয়ারডো লোফ'-এর জন্য সর্বোচ্চ কত দাম নেওয়া হচ্ছে?
- এখন আমি ডিসেম্বর ২০২৫-এর জন্য একটি রাজস্ব প্রক্ষেপণ চাই। আমার বিক্রয়ের ইতিহাস দেখুন এবং 'সাওয়ারডো লোফ'-এর জন্য আমার সেরা পারফর্মিং স্টোর থেকে ডেটা নিন। আমি কী পরিমাণ বিক্রি করব তা অনুমান করার জন্য ডিসেম্বর ২০২৫-এর একটি পূর্বাভাস চালান। তারপর, আমাদের খুঁজে পাওয়া প্রিমিয়াম মূল্যের ঠিক নিচে ব্যবহার করে আনুমানিক মোট রাজস্ব গণনা করুন (ধরা যাক $১৮)।
- এতে আমার বাড়িভাড়াটা মিটে যাবে। সবশেষে, চলুন যাতায়াতের ব্যবস্থাটা যাচাই করে নিই। প্রস্তাবিত এলাকার সবচেয়ে কাছের 'রেস্টুরেন্ট ডিপো' খুঁজে বের করুন এবং নিশ্চিত করুন যে প্রতিদিনের মালামাল পুনরায় ভরার জন্য সেখানে যেতে ৩০ মিনিটের কম সময় লাগে।
আপনার এজেন্টের পরীক্ষা শেষ হলে, আপনি আপনার ক্লাউড শেল টার্মিনালে Ctrl+C চেপে ADK ওয়েব ইন্টারফেসটি বন্ধ করতে পারেন।
৮. পরিষ্কার করা
আপনার গুগল ক্লাউড অ্যাকাউন্টে চলমান চার্জ এড়াতে, এই কোডল্যাবের সময় তৈরি করা রিসোর্সগুলো মুছে ফেলুন।
ক্লিনআপ স্ক্রিপ্টটি চালান। এই স্ক্রিপ্টটি BigQuery ডেটাসেট, ক্লাউড স্টোরেজ বাকেট এবং সেটআপের সময় তৈরি করা API কীগুলি মুছে ফেলবে।
chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh
৯. অভিনন্দন
মিশন সম্পন্ন! আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে সফলভাবে একটি লোকেশন ইন্টেলিজেন্স এজেন্ট তৈরি করেছেন।
BigQuery- তে থাকা আপনার 'এন্টারপ্রাইজ' ডেটা এবং Google Maps থেকে প্রাপ্ত বাস্তব-জগতের অবস্থানের প্রেক্ষাপটের মধ্যে সংযোগ স্থাপন করে, আপনি জটিল ব্যবসায়িক যুক্তি সম্পাদনে সক্ষম একটি শক্তিশালী টুল তৈরি করেছেন - যার পুরোটাই Model Context Protocol (MCP) এবং Gemini দ্বারা চালিত।
আপনি যা অর্জন করেছেন:
- ইনফ্রাস্ট্রাকচার অ্যাজ কোড: আপনি গুগল ক্লাউড সিএলআই টুল ব্যবহার করে একটি ডেটা স্ট্যাক প্রোভিশন করেছেন।
- এমসিপি ইন্টিগ্রেশন: আপনি জটিল এপিআই র্যাপার না লিখেই একটি এআই এজেন্টকে দুটি ভিন্ন রিমোট এমসিপি সার্ভারের (বিগকোয়েরি ও ম্যাপস) সাথে সংযুক্ত করেছেন।
- সমন্বিত যুক্তি: আপনি এমন একটি একক এজেন্ট তৈরি করেছেন যা একটি ব্যবসায়িক সমস্যা সমাধানের জন্য কৌশলগতভাবে দুটি ভিন্ন ডোমেইন থেকে প্রাপ্ত অন্তর্দৃষ্টি একত্রিত করতে সক্ষম।