ক্লাউড রানে একটি MCP সার্ভার ব্যবহার করে এমন একটি ADK এজেন্ট তৈরি করুন এবং স্থাপন করুন৷

1. ভূমিকা

এই ল্যাবটি ক্লায়েন্ট এজেন্ট পরিষেবা বাস্তবায়ন এবং স্থাপনের উপর দৃষ্টি নিবদ্ধ করে। আপনি এজেন্ট ডেভেলপমেন্ট কিট (ADK) ব্যবহার করে একটি AI এজেন্ট তৈরি করবেন যা ল্যাব 1 এ তৈরি MCP সার্ভারের মতো দূরবর্তী সরঞ্জাম ব্যবহার করে। প্রদর্শিত মূল স্থাপত্য নীতি হল উদ্বেগগুলিকে পৃথক করা, একটি স্বতন্ত্র যুক্তি স্তর (এজেন্ট) একটি সুরক্ষিত API এর মাধ্যমে একটি স্বতন্ত্র টুলিং স্তর (MCP সার্ভার) এর সাথে যোগাযোগ করে।

ল্যাব ১-এ, আপনি একটি MCP সার্ভার তৈরি করেছেন যা LLM-দের কাছে একটি কাল্পনিক চিড়িয়াখানার প্রাণীদের তথ্য সরবরাহ করে, উদাহরণস্বরূপ যখন আপনি Gemini CLI ব্যবহার করেন। এই ল্যাবে, আমরা কাল্পনিক চিড়িয়াখানার জন্য একটি ট্যুর গাইড এজেন্ট তৈরি করছি। এজেন্ট ল্যাব ১-এর একই MCP সার্ভার ব্যবহার করে চিড়িয়াখানার প্রাণীদের সম্পর্কে বিস্তারিত তথ্য পাবে এবং সেরা ট্যুর গাইড অভিজ্ঞতা তৈরি করতে উইকিপিডিয়াও ব্যবহার করবে।

অবশেষে, আমরা গুগল ক্লাউড রানে ট্যুর গাইড এজেন্ট স্থাপন করব, যাতে স্থানীয়ভাবে দৌড়ানোর পরিবর্তে সমস্ত চিড়িয়াখানার দর্শনার্থীরা এটি অ্যাক্সেস করতে পারে।

পূর্বশর্ত

• ক্লাউড রান বা এর সাথে সম্পর্কিত পরিষেবা URL-এ একটি চলমান MCP সার্ভার।
• বিলিং সক্ষম করা একটি Google ক্লাউড প্রকল্প।

তুমি কি শিখবে

• ADK স্থাপনের জন্য একটি পাইথন প্রকল্প কীভাবে গঠন করবেন।
• গুগল-এডিকে দিয়ে কীভাবে একটি টুল-ব্যবহারকারী এজেন্ট বাস্তবায়ন করবেন।
• কিভাবে একটি এজেন্টকে তার টুলসেটের জন্য একটি দূরবর্তী MCP সার্ভারের সাথে সংযুক্ত করবেন।
• ক্লাউড রানে সার্ভারলেস কন্টেইনার হিসেবে পাইথন অ্যাপ্লিকেশন কীভাবে স্থাপন করবেন।
• IAM ভূমিকা ব্যবহার করে নিরাপদ, পরিষেবা থেকে পরিষেবা প্রমাণীকরণ কীভাবে কনফিগার করবেন।
• ভবিষ্যতের খরচ এড়াতে ক্লাউড রিসোর্সগুলি কীভাবে মুছে ফেলা যায়।

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

• একটি গুগল ক্লাউড অ্যাকাউন্ট এবং গুগল ক্লাউড প্রকল্প
• ক্রোমের মতো একটি ওয়েব ব্রাউজার

2. ক্লাউড রানে কেন মোতায়েন করবেন?

ADK এজেন্টদের হোস্ট করার জন্য ক্লাউড রান একটি দুর্দান্ত পছন্দ কারণ এটি একটি সার্ভারলেস প্ল্যাটফর্ম, যার অর্থ আপনি আপনার কোডের উপর মনোযোগ দিতে পারেন, অন্তর্নিহিত অবকাঠামো পরিচালনার উপর নয়। আমরা আপনার জন্য অপারেশনাল কাজ পরিচালনা করি।

এটিকে একটি পপ-আপ দোকানের মতো ভাবুন: এটি কেবল তখনই খোলে এবং সম্পদ ব্যবহার করে যখন গ্রাহকরা (অনুরোধ) আসে। যখন কোনও গ্রাহক থাকে না, তখন এটি সম্পূর্ণরূপে বন্ধ হয়ে যায় এবং আপনাকে একটি খালি দোকানের জন্য অর্থ প্রদান করতে হয় না।

মূল বৈশিষ্ট্য

যেকোনো জায়গায় কন্টেইনার চালায়:

• তুমি একটা কন্টেইনার (ডকার ইমেজ) আনবে যার ভেতরে তোমার অ্যাপ থাকবে।
• ক্লাউড রান এটি গুগলের পরিকাঠামোতে চালায়।
• কোনও OS প্যাচিং, VM সেটআপ, বা স্কেলিং মাথাব্যথা নেই।

স্বয়ংক্রিয় স্কেলিং:

• যদি ০ জন লোক আপনার অ্যাপ ব্যবহার করে → ০ টি ইন্সট্যান্স রান হয় (শূন্য ইন্সট্যান্সে নামিয়ে আনা হয় যা সাশ্রয়ী)।
• যদি ১০০০টি অনুরোধ আসে → এটি যতগুলি প্রয়োজন ততগুলি কপি ঘুরিয়ে দেয়।

ডিফল্টরূপে স্টেটলেস:

• প্রতিটি অনুরোধ ভিন্ন ভিন্ন ক্ষেত্রে যেতে পারে।
• যদি আপনার স্টোর স্টেট প্রয়োজন হয়, তাহলে ক্লাউড এসকিউএল, ফায়ারস্টোর, অথবা মেমোরিস্টোরের মতো একটি বহিরাগত পরিষেবা ব্যবহার করুন।

যেকোনো ভাষা বা ফ্রেমওয়ার্ক সমর্থন করে:

• যতক্ষণ এটি একটি লিনাক্স কন্টেইনারে চলে, ক্লাউড রান পাইথন, গো, নোড.জেএস, জাভা, নাকি .নেট তা বিবেচনা করে না।

আপনি যা ব্যবহার করেন তার জন্য অর্থ প্রদান করুন:

• অনুরোধ-ভিত্তিক বিলিং : প্রতি অনুরোধে বিল করা + গণনার সময় (১০০ মিলিসেকেন্ড পর্যন্ত)।
• ইনস্ট্যান্স-ভিত্তিক বিলিং : সম্পূর্ণ ইনস্ট্যান্স লাইফটাইমের জন্য বিল করা হবে (প্রতি-অনুরোধের জন্য কোনও ফি নেই)।

৩. সেটআপ এবং প্রয়োজনীয়তা

স্ব-গতিসম্পন্ন পরিবেশ সেটআপ

1. গুগল ক্লাউড কনসোলে সাইন-ইন করুন এবং একটি নতুন প্রকল্প তৈরি করুন অথবা বিদ্যমান একটি পুনরায় ব্যবহার করুন। যদি আপনার ইতিমধ্যেই একটি জিমেইল বা গুগল ওয়ার্কস্পেস অ্যাকাউন্ট না থাকে, তাহলে আপনাকে অবশ্যই একটি তৈরি করতে হবে।

• এই প্রকল্পের অংশগ্রহণকারীদের জন্য প্রজেক্টের নামটি প্রদর্শন করা হবে। এটি একটি অক্ষর স্ট্রিং যা Google API গুলি ব্যবহার করে না। আপনি যেকোনো সময় এটি আপডেট করতে পারেন।
• সমস্ত Google ক্লাউড প্রোজেক্টে প্রোজেক্ট আইডি অনন্য এবং অপরিবর্তনীয় (সেট করার পরে এটি পরিবর্তন করা যাবে না)। ক্লাউড কনসোল স্বয়ংক্রিয়ভাবে একটি অনন্য স্ট্রিং তৈরি করে; সাধারণত আপনি এটি কী তা নিয়ে চিন্তা করেন না। বেশিরভাগ কোডল্যাবে, আপনাকে আপনার প্রোজেক্ট আইডি (সাধারণত PROJECT_ID হিসাবে চিহ্নিত) উল্লেখ করতে হবে। যদি আপনি জেনারেট করা আইডি পছন্দ না করেন, তাহলে আপনি অন্য একটি র্যান্ডম তৈরি করতে পারেন। বিকল্পভাবে, আপনি নিজের চেষ্টা করে দেখতে পারেন, এবং এটি উপলব্ধ কিনা তা দেখতে পারেন। এই ধাপের পরে এটি পরিবর্তন করা যাবে না এবং প্রকল্পের সময়কালের জন্য থাকবে।
• আপনার তথ্যের জন্য, তৃতীয় একটি মান আছে, একটি Project Number , যা কিছু API ব্যবহার করে। ডকুমেন্টেশনে এই তিনটি মান সম্পর্কে আরও জানুন।

সতর্কতা: একটি প্রকল্প আইডি বিশ্বব্যাপী অনন্য এবং আপনি এটি নির্বাচন করার পরে অন্য কেউ এটি ব্যবহার করতে পারবেন না। আপনিই সেই আইডির একমাত্র ব্যবহারকারী। এমনকি যদি কোনও প্রকল্প মুছে ফেলা হয়, তবুও আইডিটি আবার ব্যবহার করা যাবে না।

দ্রষ্টব্য: যদি আপনি একটি Gmail অ্যাকাউন্ট ব্যবহার করেন, তাহলে আপনি ডিফল্ট অবস্থানটি "কোন সংস্থা নয়" তে সেট করে রাখতে পারেন। যদি আপনি একটি Google Workspace অ্যাকাউন্ট ব্যবহার করেন, তাহলে এমন একটি অবস্থান বেছে নিন যা আপনার সংস্থার জন্য যুক্তিসঙ্গত।

2. এরপর, ক্লাউড রিসোর্স/API ব্যবহার করার জন্য আপনাকে ক্লাউড কনসোলে বিলিং সক্ষম করতে হবে। এই কোডল্যাবটি চালানোর জন্য খুব বেশি খরচ হবে না, এমনকি কিছু খরচও হবে না। এই টিউটোরিয়ালের বাইরে বিলিং এড়াতে রিসোর্স বন্ধ করতে, আপনি আপনার তৈরি রিসোর্সগুলি মুছে ফেলতে পারেন অথবা প্রকল্পটি মুছে ফেলতে পারেন। নতুন গুগল ক্লাউড ব্যবহারকারীরা $300 USD ফ্রি ট্রায়াল প্রোগ্রামের জন্য যোগ্য।

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

ক্লাউড শেল এডিটরে নেভিগেট করুন

যদি স্ক্রিনের নীচে টার্মিনালটি না দেখা যায়, তাহলে এটি খুলুন:

• টার্মিনাল ক্লিক করুন
• নতুন টার্মিনাল ক্লিক করুন

টার্মিনালে, এই কমান্ড দিয়ে আপনার প্রকল্পটি সেট করুন। যদি আপনি ল্যাব 1 সম্পন্ন করে থাকেন, তাহলে নিশ্চিত করুন যে আপনি একই প্রকল্প আইডি ব্যবহার করছেন:

gcloud config set project [YOUR-PROJECT-ID]

যদি আপনি আপনার প্রজেক্ট আইডি মনে রাখতে না পারেন, তাহলে আপনি আপনার সমস্ত প্রজেক্ট আইডি তালিকাভুক্ত করতে পারেন:

gcloud projects list | awk '/PROJECT_ID/{print $2}'

৪. অনুমোদনের অনুরোধ করা হলে, চালিয়ে যেতে অনুমোদনে ক্লিক করুন।

৫. আপনার এই বার্তাটি দেখা উচিত:

Updated property [core/project].

If you see a `WARNING` and are asked `Do you want to continue (Y/n)?`,

then you have likely entered the project ID incorrectly. Press `n`,

press `Enter`, and try to run the `gcloud config set project` command again.

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

API গুলি সক্ষম করুন এবং পরিবেশ ভেরিয়েবল সেট করুন

সমস্ত প্রয়োজনীয় পরিষেবা সক্ষম করুন:

gcloud services enable \
    run.googleapis.com \
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com \
    aiplatform.googleapis.com \
    compute.googleapis.com 

প্রত্যাশিত আউটপুট

Operation "operations/acat.p2-[GUID]" finished successfully.

৫. প্রজেক্ট ফোল্ডার তৈরি করুন

প্রকল্প ডিরেক্টরি তৈরি করুন।

এই কমান্ডটি এজেন্টের সোর্স কোডের জন্য ল্যাবের জন্য একটি প্রধান ফোল্ডার তৈরি করে।

cd && mkdir zoo_guide_agent && cd zoo_guide_agent

requirements.txt ফাইলটি তৈরি করুন। এই ফাইলটিতে আপনার এজেন্টের প্রয়োজনীয় পাইথন লাইব্রেরিগুলির তালিকা রয়েছে। নিম্নলিখিত কমান্ডটি ফাইলটি তৈরি করে এবং এটি পূরণ করে।

cloudshell edit requirements.txt

google-adk==1.14.0
langchain-community==0.3.27
wikipedia==1.4.0

আপনার বর্তমান প্রকল্প, অঞ্চল এবং ব্যবহারকারীর জন্য ভেরিয়েবল সেট করুন। এই কমান্ডগুলি চালানোর জন্য এটি আরও শক্তিশালী উপায়।

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export SERVICE_ACCOUNT="${PROJECT_NUMBER}[e-mail]"

zoo_guide_agent ডিরেক্টরিতে এজেন্টকে প্রমাণীকরণের জন্য একটি .env ফাইল তৈরি করুন এবং খুলুন।

cloudshell edit .env

ক্লাউডশেল এডিট কমান্ড টার্মিনালের উপরে এডিটরে .env ফাইলটি খুলবে। .env ফাইলে নিম্নলিখিতটি লিখুন এবং টার্মিনালে ফিরে যান।

MODEL="gemini-2.5-flash"
SERVICE_ACCOUNT="${PROJECT_NUMBER}[e-mail]"

MCP সার্ভার URL যোগ করা হচ্ছে। যদি আপনি ল্যাব ১ সম্পন্ন করে থাকেন, তাহলে ল্যাব ১ এ তৈরি করা MCP সার্ভারটি ব্যবহার করতে এই পদক্ষেপগুলি অনুসরণ করুন:

দ্রষ্টব্য: যদি আপনি ল্যাব ১ সম্পন্ন করে থাকেন এবং সেই ল্যাবে তৈরি MCP সার্ভারটি ব্যবহার করতে চান, তাহলে নিম্নলিখিত তিনটি কমান্ড চালান। যদি আপনি ইতিমধ্যেই লাইভ ইভেন্টের সময় আপনাকে দেওয়া পাবলিক MCP সার্ভার লিঙ্কটি ব্যবহার করেন তবে আপনাকে এই দুটি কমান্ড চালানোর প্রয়োজন নেই।

1. দূরবর্তী MCP সার্ভারে কল করার জন্য ক্লাউড রান পরিষেবা পরিচয়ের অনুমতি দিন

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/run.invoker"

2. ল্যাব ১ থেকে MCP সার্ভার URL টি একটি পরিবেশ ভেরিয়েবলে সংরক্ষণ করুন।

echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp" >> .env

যদি আপনি একটি পাবলিক MCP সার্ভার লিঙ্ক ব্যবহার করেন, তাহলে নিম্নলিখিতটি চালান, এবং PROJECT_NUMBER যা দেওয়া আছে তা দিয়ে প্রতিস্থাপন করুন।

echo -e "\nMCP_SERVER_URL=https://zoo-mcp-server-${PROJECT_NUMBER}.europe-west1.run.app/mcp" >> .env

৬. এজেন্ট ওয়ার্কফ্লো তৈরি করুন

init .py ফাইল তৈরি করুন

init .py ফাইলটি তৈরি করুন। এই ফাইলটি পাইথনকে বলে যে zoo_guide_agent ডিরেক্টরিটি একটি প্যাকেজ।

cloudshell edit __init__.py

উপরের কমান্ডটি কোড এডিটরটি খুলবে। নিম্নলিখিত কোডটি __init__.py তে যুক্ত করুন:

from . import agent

প্রধান agent.py ফাইল তৈরি করুন

প্রধান agent.py ফাইল তৈরি করুন। এই কমান্ডটি পাইথন ফাইল তৈরি করে এবং আপনার মাল্টি-এজেন্ট সিস্টেমের জন্য সম্পূর্ণ কোডটি পেস্ট করে।

cloudshell edit agent.py

ধাপ ১: আমদানি এবং প্রাথমিক সেটআপ

এই প্রথম ব্লকটি ADK এবং Google ক্লাউড থেকে সমস্ত প্রয়োজনীয় লাইব্রেরি নিয়ে আসে। এটি লগিং সেট আপ করে এবং আপনার .env ফাইল থেকে পরিবেশগত ভেরিয়েবল লোড করে, যা আপনার মডেল এবং সার্ভার URL অ্যাক্সেস করার জন্য অত্যন্ত গুরুত্বপূর্ণ।

আপনার agent.py ফাইলে নিম্নলিখিত কোডটি যোগ করুন:

import os
import logging
import google.cloud.logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StreamableHTTPConnectionParams
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

cloud_logging_client = google.cloud.logging.Client()
cloud_logging_client.setup_logging()

load_dotenv()

model_name = os.getenv("MODEL")

ধাপ ২: সরঞ্জামগুলি সংজ্ঞায়িত করা (এজেন্টের ক্ষমতা)

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

agent.py এর নীচে নিম্নলিখিত কোডটি যোগ করুন:

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}


# Configuring the MCP Tool to connect to the Zoo MCP server

mcp_server_url = os.getenv("MCP_SERVER_URL")
if not mcp_server_url:
    raise ValueError("The environment variable MCP_SERVER_URL is not set.")

def get_id_token():
    """Get an ID token to authenticate with the MCP server."""
    target_url = os.getenv("MCP_SERVER_URL")
    audience = target_url.split('/mcp/')[0]
    request = google.auth.transport.requests.Request()
    id_token = google.oauth2.id_token.fetch_id_token(request, audience)
    return id_token

"""
# Use this code if you are using the public MCP Server and comment out the code below defining mcp_tools
mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url=mcp_server_url
    )
)
"""

mcp_tools = MCPToolset(
            connection_params=StreamableHTTPConnectionParams(
                url=mcp_server_url,
                headers={
                    "Authorization": f"Bearer {get_id_token()}",
                },
            ),
        )

# Configuring the Wikipedia Tool
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())
)

তিনটি হাতিয়ার ব্যাখ্যা করা হয়েছে

1. add_prompt_to_state

এই টুলটি একজন চিড়িয়াখানার দর্শনার্থী কী জিজ্ঞাসা করে তা মনে রাখে। যখন একজন দর্শনার্থী জিজ্ঞাসা করে, "সিংহগুলো কোথায়?", তখন এই টুলটি সেই নির্দিষ্ট প্রশ্নটি এজেন্টের স্মৃতিতে সংরক্ষণ করে যাতে কর্মপ্রবাহের অন্যান্য এজেন্টরা জানতে পারে কী গবেষণা করতে হবে।

কিভাবে: এটি একটি পাইথন ফাংশন যা shared tool_context.state অভিধানে ভিজিটরের প্রম্পট লিখে। এই টুল কনটেক্সট একটি একক কথোপকথনের জন্য এজেন্টের স্বল্পমেয়াদী মেমরির প্রতিনিধিত্ব করে। একজন এজেন্ট দ্বারা স্টেটে সংরক্ষিত ডেটা ওয়ার্কফ্লোতে পরবর্তী এজেন্ট দ্বারা পড়া যেতে পারে।

2. MCPToolset 🦁

এটি ল্যাব ১-এ তৈরি চিড়িয়াখানার MCP সার্ভারের সাথে ট্যুর গাইড এজেন্টকে সংযুক্ত করতে ব্যবহৃত হয়। এই সার্ভারে আমাদের প্রাণীদের নাম, বয়স এবং ঘেরের মতো নির্দিষ্ট তথ্য অনুসন্ধানের জন্য বিশেষ সরঞ্জাম রয়েছে।

কিভাবে: এটি চিড়িয়াখানার ব্যক্তিগত সার্ভার URL-এর সাথে নিরাপদে সংযোগ স্থাপন করে। এটি get_id_token ব্যবহার করে স্বয়ংক্রিয়ভাবে একটি নিরাপদ "কীকার্ড" (একটি পরিষেবা অ্যাকাউন্ট আইডি টোকেন) পায় যার মাধ্যমে এটির পরিচয় প্রমাণ করা যায় এবং অ্যাক্সেস পাওয়া যায়।

3. LangchainTool 🌍

এটি ট্যুর গাইড এজেন্টকে সাধারণ বিশ্ব জ্ঞান প্রদান করে। যখন কোনও দর্শনার্থী এমন কোনও প্রশ্ন জিজ্ঞাসা করে যা চিড়িয়াখানার ডাটাবেসে নেই, যেমন "বন্যে সিংহরা কী খায়?", এই টুলটি এজেন্টকে উইকিপিডিয়ায় উত্তরটি খুঁজতে দেয়।

কিভাবে: এটি একটি অ্যাডাপ্টার হিসেবে কাজ করে, যা আমাদের এজেন্টকে LangChain লাইব্রেরি থেকে পূর্বে তৈরি WikipediaQueryRun টুল ব্যবহার করার অনুমতি দেয়।

সম্পদ:

• এমসিপি টুলসেট
• ফাংশন টুল
• রাজ্য

ধাপ ৩: বিশেষজ্ঞ এজেন্টদের সংজ্ঞা দেওয়া

এরপর আমরা গবেষক এজেন্ট এবং প্রতিক্রিয়া ফর্ম্যাটার এজেন্টকে সংজ্ঞায়িত করব। গবেষক এজেন্ট হল আমাদের অপারেশনের "মস্তিষ্ক"। এই এজেন্ট শেয়ার্ড State থেকে ব্যবহারকারীর প্রম্পট নেয়, এর শক্তিশালী টুলগুলি (চিড়িয়াখানার MCP সার্ভার টুল এবং উইকিপিডিয়া টুল) পরীক্ষা করে এবং উত্তর খুঁজে পেতে কোনগুলি ব্যবহার করতে হবে তা নির্ধারণ করে।

প্রতিক্রিয়া ফর্ম্যাটার এজেন্টের ভূমিকা হল উপস্থাপনা। এটি নতুন তথ্য খুঁজে বের করার জন্য কোনও সরঞ্জাম ব্যবহার করে না। পরিবর্তে, এটি গবেষক এজেন্টের সংগৃহীত কাঁচা তথ্য (রাজ্যের মাধ্যমে প্রেরিত) গ্রহণ করে এবং LLM-এর ভাষা দক্ষতা ব্যবহার করে এটিকে একটি বন্ধুত্বপূর্ণ, কথোপকথনমূলক প্রতিক্রিয়ায় রূপান্তরিত করে।

agent.py এর নীচে নিম্নলিখিত কোডটি যোগ করুন:

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    {{ PROMPT }}
    """,
    tools=[
        mcp_tools,
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    {{ research_data }}
    """
)

ধাপ ৪: ওয়ার্কফ্লো এজেন্ট

চিড়িয়াখানা ভ্রমণের জন্য ওয়ার্কফ্লো এজেন্ট 'ব্যাক-অফিস' ম্যানেজার হিসেবে কাজ করে। এটি গবেষণার অনুরোধ গ্রহণ করে এবং উপরে সংজ্ঞায়িত দুটি এজেন্টকে সঠিক ক্রমে তাদের কাজ সম্পাদন নিশ্চিত করে: প্রথমে গবেষণা, তারপর ফর্ম্যাটিং। এটি একজন দর্শনার্থীর প্রশ্নের উত্তর দেওয়ার জন্য একটি অনুমানযোগ্য এবং নির্ভরযোগ্য প্রক্রিয়া তৈরি করে।

কিভাবে: এটি একটি SequentialAgent , একটি বিশেষ ধরণের এজেন্ট যা নিজের জন্য চিন্তা করে না। এর একমাত্র কাজ হল একটি নির্দিষ্ট ক্রমানুসারে sub_agents (গবেষক এবং ফর্ম্যাটার) তালিকা চালানো, যা স্বয়ংক্রিয়ভাবে ভাগ করা মেমরিটিকে একটি থেকে অন্যটিতে প্রেরণ করে।

agent.py এর নীচে এই কোড ব্লকটি যুক্ত করুন:

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

চূড়ান্ত ধাপ: মূল কর্মপ্রবাহ একত্রিত করা

এই এজেন্টটিকে root_agent হিসেবে মনোনীত করা হয়েছে, যা ADK ফ্রেমওয়ার্ক সকল নতুন কথোপকথনের সূচনা বিন্দু হিসেবে ব্যবহার করে। এর প্রাথমিক ভূমিকা হল সামগ্রিক প্রক্রিয়াটি পরিচালনা করা। এটি প্রাথমিক নিয়ন্ত্রক হিসেবে কাজ করে, কথোপকথনের প্রথম পালা পরিচালনা করে।

agent.py এর নীচে কোডের এই চূড়ান্ত ব্লকটি যুক্ত করুন:

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

আপনার agent.py ফাইলটি এখন সম্পূর্ণ! এইভাবে এটি তৈরি করে, আপনি দেখতে পাবেন কিভাবে প্রতিটি উপাদান - সরঞ্জাম, কর্মী এজেন্ট এবং ব্যবস্থাপক এজেন্ট - চূড়ান্ত, বুদ্ধিমান সিস্টেম তৈরিতে একটি নির্দিষ্ট ভূমিকা পালন করে। এরপর, স্থাপনা!

৭. স্থাপনের জন্য আবেদনপত্র প্রস্তুত করুন

আপনার স্থানীয় পরিবেশ প্রস্তুত থাকলে, পরবর্তী ধাপ হল আপনার Google ক্লাউড প্রকল্পটি স্থাপনের জন্য প্রস্তুত করা। এর মধ্যে আপনার এজেন্টের ফাইল কাঠামোর চূড়ান্ত পরীক্ষা করা জড়িত যাতে এটি স্থাপন কমান্ডের সাথে সামঞ্জস্যপূর্ণ হয়। আরও গুরুত্বপূর্ণ বিষয় হল, আপনি একটি গুরুত্বপূর্ণ IAM অনুমতি কনফিগার করেন যা আপনার স্থাপন করা ক্লাউড রান পরিষেবাকে আপনার পক্ষে কাজ করতে এবং Vertex AI মডেলগুলিকে কল করতে দেয়। এই ধাপটি সম্পূর্ণ করলে নিশ্চিত হয় যে ক্লাউড পরিবেশ আপনার এজেন্ট সফলভাবে চালানোর জন্য প্রস্তুত।

সোর্স কমান্ডটি চালিয়ে আপনার শেল সেশনে ভেরিয়েবলগুলি লোড করুন।

source .env

পরিষেবা অ্যাকাউন্টটিকে Vertex AI ব্যবহারকারীর ভূমিকা প্রদান করুন, যা এটিকে ভবিষ্যদ্বাণী করার এবং Google এর মডেলগুলিকে কল করার অনুমতি দেয়।

# Grant the "Vertex AI User" role to your service account
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT" \
  --role="roles/aiplatform.user"

৮. ADK CLI ব্যবহার করে এজেন্ট স্থাপন করুন

আপনার স্থানীয় কোড প্রস্তুত এবং আপনার Google ক্লাউড প্রজেক্ট প্রস্তুত থাকায়, এজেন্ট স্থাপনের সময় এসেছে। আপনি adk deploy cloud_run কমান্ড ব্যবহার করবেন, এটি একটি সুবিধাজনক টুল যা সম্পূর্ণ স্থাপনার কর্মপ্রবাহকে স্বয়ংক্রিয় করে তোলে। এই একক কমান্ডটি আপনার কোড প্যাকেজ করে, একটি কন্টেইনার ইমেজ তৈরি করে, এটিকে আর্টিফ্যাক্ট রেজিস্ট্রিতে পুশ করে এবং ক্লাউড রানে পরিষেবা চালু করে, এটি ওয়েবে অ্যাক্সেসযোগ্য করে তোলে।

স্থাপন করুন

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

দ্রষ্টব্য: নীচের এই ডিপ্লয় কমান্ডটি চালানো শেষ হতে কয়েক মিনিট সময় লাগবে।

# Run the deployment command
uvx --from google-adk \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --labels=dev-tutorial=codelab-adk

প্রম্পট গ্রহণ করুন

আপনাকে নিম্নলিখিতগুলি জিজ্ঞাসা করা হতে পারে:

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?

Y টাইপ করুন এবং ENTER টিপুন।

আপনাকে নিম্নলিখিতগুলি জিজ্ঞাসা করা হতে পারে:

Allow unauthenticated invocations to [your-service-name] (y/N)?.

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

দ্রষ্টব্য: URL সহ যে কেউ এই এজেন্টে অ্যাক্সেস করতে পারবেন, তাই পরীক্ষার জন্য এটিই সবচেয়ে ভালো।

স্থাপনার লিঙ্কটি পান

সফলভাবে কার্যকর করার পর, কমান্ডটি মোতায়েন করা ক্লাউড রান পরিষেবার URL প্রদান করবে। (এটি দেখতে https://zoo-tour-guide-123456789.europe-west1.run.app এর মতো হবে)। পরবর্তী কাজের জন্য এই URL টি অনুলিপি করুন।

৯. মোতায়েন করা এজেন্ট পরীক্ষা করুন

আপনার এজেন্ট এখন ক্লাউড রানে লাইভ হওয়ার সাথে সাথে, আপনাকে একটি পরীক্ষা করতে হবে যাতে নিশ্চিত করা যায় যে স্থাপনা সফল হয়েছে এবং এজেন্টটি প্রত্যাশা অনুযায়ী কাজ করছে। ADK-এর ওয়েব ইন্টারফেস অ্যাক্সেস করতে এবং এজেন্টের সাথে যোগাযোগ করতে আপনি পাবলিক সার্ভিস URL ( https://zoo-tour-guide-123456789.europe-west1.run.app/ এর মতো কিছু) ব্যবহার করবেন।

আপনার ওয়েব ব্রাউজারে পাবলিক ক্লাউড রান সার্ভিস URL খুলুন। যেহেতু আপনি --with_ui flag ব্যবহার করেছেন, তাই আপনার ADK ডেভেলপার UI দেখা উচিত।

উপরের ডানদিকে Token Streaming চালু করুন।

আপনি এখন চিড়িয়াখানার এজেন্টের সাথে যোগাযোগ করতে পারেন।

নতুন কথোপকথন শুরু করতে hello টাইপ করুন এবং এন্টার টিপুন।

ফলাফল লক্ষ্য করুন। এজেন্টের দ্রুত সাড়া দিয়ে শুভেচ্ছা জানানো উচিত:

"Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"

এজেন্টকে এই ধরনের প্রশ্ন জিজ্ঞাসা করুন:

Where can I find the polar bears in the zoo and what is their diet?

এজেন্ট ফ্লো ব্যাখ্যা করা হয়েছে

আপনার সিস্টেমটি একটি বুদ্ধিমান, বহু-এজেন্ট দল হিসেবে কাজ করে। ব্যবহারকারীর প্রশ্ন থেকে চূড়ান্ত, বিস্তারিত উত্তর পর্যন্ত একটি মসৃণ এবং দক্ষ প্রবাহ নিশ্চিত করার জন্য প্রক্রিয়াটি একটি স্পষ্ট ক্রম দ্বারা পরিচালিত হয়।

১. চিড়িয়াখানার অভিবাদন (স্বাগতম ডেস্ক )

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

এর কাজ: কথোপকথন শুরু করা। এর নির্দেশ হল ব্যবহারকারীকে অভ্যর্থনা জানানো এবং জিজ্ঞাসা করা যে তারা কোন প্রাণী সম্পর্কে জানতে চায়।

এর টুল: যখন ব্যবহারকারী উত্তর দেয়, তখন গ্রিটার তার add_prompt_to_state টুল ব্যবহার করে তাদের সঠিক শব্দগুলি ক্যাপচার করে (যেমন, "সিংহ সম্পর্কে আমাকে বলুন") এবং সেগুলি সিস্টেমের মেমরিতে সংরক্ষণ করে।

হ্যান্ডঅফ: প্রম্পটটি সংরক্ষণ করার পর, এটি তাৎক্ষণিকভাবে তার সাব-এজেন্ট, tour_guide_workflow-এর কাছে নিয়ন্ত্রণ হস্তান্তর করে।

২. দ্য কম্প্রিহেনসিভ রিসার্চার (সুপার-রিসার্চার)

এটি মূল কর্মপ্রবাহের প্রথম ধাপ এবং অপারেশনের "মস্তিষ্ক"। একটি বৃহৎ দলের পরিবর্তে, এখন আপনার কাছে একটি একক, অত্যন্ত দক্ষ এজেন্ট রয়েছে যে সমস্ত উপলব্ধ তথ্য অ্যাক্সেস করতে পারে।

এর কাজ: ব্যবহারকারীর প্রশ্ন বিশ্লেষণ করা এবং একটি বুদ্ধিমান পরিকল্পনা তৈরি করা। এটি ভাষা মডেলের শক্তিশালী টুল ব্যবহার ক্ষমতা ব্যবহার করে সিদ্ধান্ত নেয় যে এটির প্রয়োজন কিনা:

• চিড়িয়াখানার রেকর্ড থেকে অভ্যন্তরীণ তথ্য (এমসিপি সার্ভারের মাধ্যমে)।
• ওয়েব থেকে সাধারণ জ্ঞান (উইকিপিডিয়া এপিআই এর মাধ্যমে)।
• অথবা, জটিল প্রশ্নের জন্য, উভয়ই।

এর ক্রিয়া: এটি প্রয়োজনীয় সমস্ত কাঁচা তথ্য সংগ্রহের জন্য প্রয়োজনীয় সরঞ্জাম(গুলি) কার্যকর করে। উদাহরণস্বরূপ, যদি জিজ্ঞাসা করা হয় "আমাদের সিংহের বয়স কত এবং তারা বন্য অবস্থায় কী খায়?", তাহলে এটি বয়সের জন্য MCP সার্ভার এবং খাদ্য তথ্যের জন্য উইকিপিডিয়া টুল কল করবে।

৩. রেসপন্স ফর্ম্যাটার (উপস্থাপক)

একবার বিস্তৃত গবেষক সমস্ত তথ্য সংগ্রহ করলে, এটিই চূড়ান্ত এজেন্ট যা চালানো হবে।

এর কাজ: চিড়িয়াখানা ট্যুর গাইডের বন্ধুত্বপূর্ণ কণ্ঠস্বর হিসেবে কাজ করা। এটি কাঁচা তথ্য (যা এক বা উভয় উৎস থেকে হতে পারে) গ্রহণ করে এবং এটিকে পালিশ করে।

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

চূড়ান্ত ফলাফল: এই এজেন্ট দ্বারা তৈরি টেক্সট হল সম্পূর্ণ, বিস্তারিত উত্তর যা ব্যবহারকারী চ্যাট উইন্ডোতে দেখতে পান।

আপনি যদি এজেন্ট তৈরি সম্পর্কে আরও জানতে আগ্রহী হন, তাহলে নিম্নলিখিত সংস্থানগুলি দেখুন:

1. ADK ডক্স
2. ADK এজেন্টদের জন্য কাস্টম টুল তৈরি করা

১০. পরিবেশ পরিষ্কার করুন

gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet

১১. অভিনন্দন

কোডল্যাবটি সম্পন্ন করার জন্য অভিনন্দন।

আমরা যা কভার করেছি

• ADK কমান্ড-লাইন ইন্টারফেস ব্যবহার করে স্থাপনার জন্য একটি পাইথন প্রকল্প কীভাবে গঠন করবেন।
• SequentialAgent এবং ParallelAgent ব্যবহার করে কিভাবে একটি মাল্টি-এজেন্ট ওয়ার্কফ্লো বাস্তবায়ন করবেন।
• MCPToolset ব্যবহার করে একটি দূরবর্তী MCP সার্ভারের সাথে কীভাবে সংযোগ করবেন যাতে এর সরঞ্জামগুলি ব্যবহার করা যায়।
• উইকিপিডিয়া এপিআই-এর মতো বাহ্যিক সরঞ্জামগুলিকে একীভূত করে কীভাবে অভ্যন্তরীণ ডেটা বৃদ্ধি করা যায়।
• adk deploy কমান্ড ব্যবহার করে ক্লাউড রানে সার্ভারলেস কন্টেইনার হিসেবে এজেন্ট কীভাবে স্থাপন করবেন।

১২. জরিপ

আউটপুট:

আপনি এই টিউটোরিয়ালটি কীভাবে ব্যবহার করবেন?

শুধু এটি পড়ুন এটি পড়ুন এবং অনুশীলনগুলি সম্পূর্ণ করুন।