ADK for Go সহ এজেন্ট স্টার্টার প্যাক

১. ভূমিকা

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

প্রোটোটাইপ থেকে প্রোডাকশন এজেন্টে রূপান্তরের সময় এমন কিছু ইঞ্জিনিয়ারিং চ্যালেঞ্জ আসে যা Go অত্যন্ত দক্ষতার সাথে সামলাতে পারে। স্ট্রাকচার্ড LLM আউটপুট পার্স করার সময় Go-এর স্ট্যাটিক টাইপিং রানটাইম ত্রুটি দূর করে। এর লাইটওয়েট গোরুটিনগুলো, যা OS থ্রেডের কয়েক মেগাবাইটের তুলনায় মাত্র কয়েক কিলোবাইট স্ট্যাক মেমরি দিয়ে শুরু হয়, এজেন্টদেরকে ভারী থ্রেড ম্যানেজমেন্টের বাড়তি চাপ ছাড়াই হাজার হাজার টুলের যুগপৎ এক্সিকিউশন পরিচালনা করতে সক্ষম করে।

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

আপনাকে যা করতে হবে:

• এজেন্ট স্টার্টার প্যাক ব্যবহার করে একটি প্রোডাকশন-রেডি এজেন্ট প্রজেক্ট তৈরি করুন।
• আপনার এজেন্ট ডিবাগ ও পরীক্ষা করার জন্য স্থানীয় এজেন্ট ডেভেলপমেন্ট কিট ওয়েব UI ব্যবহার করুন।
• Go-ভিত্তিক ADK এজেন্ট লজিক তৈরি করুন এবং বুঝুন
• ইউনিট এবং এন্ড-টু-এন্ড (E2E) টেস্ট চালান
• এজেন্টটিকে নিরাপদে ক্লাউড রান-এ স্থাপন করুন।

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

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

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

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

যদি আপনার আগে থেকে একটি না থাকে:

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

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

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

1. Google Cloud কনসোলের শীর্ষে থাকা Activate Cloud Shell-এ ক্লিক করুন।
2. ক্লাউড শেলে সংযুক্ত হওয়ার পর, আপনার প্রমাণীকরণ যাচাই করতে এই কমান্ডটি চালান:

gcloud auth list

3. আপনার প্রজেক্টটি gcloud ব্যবহারের জন্য কনফিগার করা হয়েছে কিনা তা নিশ্চিত করতে নিম্নলিখিত কমান্ডটি চালান:

gcloud config get project

4. প্রকল্পটি প্রত্যাশা অনুযায়ী আছে কিনা তা নিশ্চিত করুন, এবং তারপর আপনার প্রজেক্ট আইডি সেট করতে নিচের কমান্ডটি চালান:

export PROJECT_ID=$(gcloud config get project)

৩. এজেন্ট স্টার্টার প্যাক দিয়ে শুরু করুন

সুখবরটি হলো, আপনাকে একেবারে গোড়া থেকে শুরু করতে হবে না। এজেন্ট স্টার্টার প্যাক হলো একটি CLI টুল যা CI/CD পাইপলাইন, ইনফ্রাস্ট্রাকচার কনফিগারেশন এবং বয়লারপ্লেট কোড সহ একটি প্রোডাকশন-রেডি ফোল্ডার স্ট্রাকচার তৈরি করে দেয়।

শুরু করতে, uvx দিয়ে বিল্ড তৈরির কমান্ডটি চালান:

uvx agent-starter-pack create

CLI আপনাকে একটি ইন্টারেক্টিভ সেটআপের মাধ্যমে নির্দেশনা দেবে। এই প্রজেক্টের জন্য, নিম্নলিখিত অপশনগুলো নির্বাচন করুন:

• প্রকল্পের নাম: my-first-go-agent
• টেমপ্লেট: বিকল্প ৬ (গো এডিকে, এ২এ সহ গো এজেন্ট)
• CI/CD: বিকল্প ৩ (GitHub Actions)
• অঞ্চল: us-central1

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

একবার আপনি সবুজ রঙের ' সফল!' বার্তাটি দেখতে পেলে, আপনি পরবর্তী ধাপে যাওয়ার জন্য প্রস্তুত।

৪. স্থানীয়ভাবে এজেন্টকে দৃশ্যমান করা

ADK-এর সবচেয়ে সুবিধাজনক বৈশিষ্ট্যগুলোর মধ্যে একটি হলো আপনার এজেন্টকে ডেপ্লয় করার আগে দৃশ্যত ডিবাগ করার ক্ষমতা। নিচের কমান্ডগুলো চালানোর মাধ্যমে, আপনি একটি বিল্ট-ইন UI সহ একটি স্থানীয় ডেভেলপমেন্ট সার্ভার চালু করতে পারবেন। হ্যাঁ, এতে একটি চ্যাট উইন্ডো আছে, কিন্তু এটি ইভেন্ট, টুল কল এবং আরও অনেক কিছু ট্রেস করার মাধ্যমে তার চেয়েও অনেক বেশি কিছু করে।

আপনার প্রজেক্ট ডিরেক্টরিতে যান এবং প্লেগ্রাউন্ডটি চালু করুন:

cd my-first-go-agent
make install
make playground

প্লেগ্রাউন্ডটি চালু হয়ে গেলে, আপনার নতুন তৈরি করা এজেন্টের সাথে ইন্টারঅ্যাক্ট করার জন্য ক্লাউড শেলে ওয়েব প্রিভিউটি খুলুন।

এজেন্টটিকে রিঅ্যাক্ট (রিজনিং অ্যান্ড অ্যাক্টিং) প্যাটার্ন দিয়ে কনফিগার করা হয়েছে—এটি এমন একটি ফ্রেমওয়ার্ক যা এজেন্টিক এআই-এর ক্ষেত্রে একটি ভিত্তি হয়ে উঠেছে। রিঅ্যাক্ট প্যাটার্নের 'চিন্তা', 'কর্ম' এবং 'পর্যবেক্ষণ'-এর অবিচ্ছিন্ন চক্র সমস্যা সমাধান এবং বোধগম্যতাকে উন্নত করে, যা এজেন্টের সিদ্ধান্ত গ্রহণ প্রক্রিয়াকে স্বচ্ছ করে তোলে।

উদাহরণস্বরূপ, আপনি যদি আবহাওয়া জানতে চান, এজেন্টটি আপনার উদ্দেশ্য বুঝতে পারে, get_weather টুলটি চালু করে এবং স্ট্রাকচার্ড ডেটা ফেরত দেয়।

৫. কোডটি বোঝা

এখন যেহেতু আমরা এজেন্টটিকে কাজ করতে দেখেছি, চলুন সেই Go কোডটি দেখি যা এটিকে কার্যকর করে। এর লজিকটি agent/agent.go ফাইলে রয়েছে। এই ফাইলটি টুলের সংজ্ঞা, মডেলের কনফিগারেশন এবং প্রারম্ভিকীকরণ পরিচালনা করে।

লার্জ ল্যাঙ্গুয়েজ মডেল (LLM) আপনার কোডের সাথে কীভাবে কাজ করবে তা নির্ধারণ করতে ADK স্ট্যান্ডার্ড Go স্ট্রাক্ট ব্যবহার করে। আমাদের ওয়েদার টুলের ইনপুট প্যারামিটারগুলো নির্ধারণ করতে, আমরা json এবং jsonschema ট্যাগসহ একটি স্ট্রাক্ট তৈরি করি:

type GetWeatherArgs struct {
    City string `json:"city" jsonschema:"City name to get weather for"`
}

টুলটি কার্যকর হওয়ার পর এজেন্টের কাছে যে ডেটার কাঠামো ফেরত আসে, তা GetWeatherResult নির্ধারণ করে:

// GetWeatherResult defines the output for the get_weather tool.
type GetWeatherResult struct {
	Weather string `json:"weather"`
}

GetWeather হলো Go-এর একটি স্ট্যান্ডার্ড ফাংশন, যা tool.Context এবং arguments struct গ্রহণ করে, বিজনেস লজিক সম্পাদন করে এবং result struct রিটার্ন করে।

// GetWeather returns mock weather data for a city.
func GetWeather(_ tool.Context, args GetWeatherArgs) (GetWeatherResult, error) {
	return GetWeatherResult{
		Weather: "It's sunny and 72°F in " + args.City,
	}, nil
}

NewRootAgent ফাংশনটি অ্যাপ্লিকেশন লঞ্চারের প্রয়োজনীয় agent.Agent ইনস্ট্যান্সটি তৈরি করে ফেরত দেওয়ার দায়িত্বে থাকে। এটি genai.BackendVertexAI দ্বারা সমর্থিত একটি gemini-2.5-flash মডেল ইনস্ট্যান্স তৈরি করার মাধ্যমে মডেল কনফিগারেশন শুরু করে।

এরপরে, এটি স্থানীয় GetWeather ফাংশনটিকে একটি functiontool মধ্যে আবদ্ধ করার মাধ্যমে Go কোড এবং LLM-এর মধ্যেকার ব্যবধান পূরণ করে। এই ধাপে get_weather নামে টুলটি নিবন্ধিত হয় এবং মডেলের প্রেক্ষাপটের জন্য প্রয়োজনীয় বিবরণ প্রদান করা হয়। সবশেষে, এটি llmagent.New ব্যবহার করে এজেন্টটি তৈরি করে, যা প্রারম্ভিক Gemini মডেল, এজেন্টের আচরণ নির্ধারণকারী সিস্টেম নির্দেশাবলী এবং উপলব্ধ টুলগুলোর স্লাইসকে একটি একক ইউনিটে একত্রিত করে।

// NewRootAgent creates and returns the root agent with all configured tools.
func NewRootAgent(ctx context.Context) (agent.Agent, error) {
	model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
		Backend: genai.BackendVertexAI,
	})

	weatherTool, err := functiontool.New(functiontool.Config{
		Name:        "get_weather",
		Description: "Get the current weather for a city.",
	}, GetWeather)

	rootAgent, err := llmagent.New(llmagent.Config{
		Name:        "my-first-go-agent",
		Model:       model,
		Description: "A helpful AI assistant.",
		Instruction: "You are a helpful AI assistant designed to provide accurate and useful information.",
		Tools:       []tool.Tool{weatherTool},
	})
	// ... (additional logic omitted for brevity)
	return rootAgent, nil
}

৬. পরীক্ষা

প্রকল্পটিতে অভ্যন্তরীণ লজিকের জন্য ইউনিট টেস্ট এবং সার্ভার ইন্টিগ্রেশনের জন্য এন্ড-টু-এন্ড টেস্ট উভয়ই রয়েছে।

agent/agent_test.go ফাইলে, আউটপুট স্ট্রিংটি প্রত্যাশার সাথে মেলে কিনা তা যাচাই করার জন্য GetWeather ফাংশনটিকে একগুচ্ছ টেস্ট কেস সহ কল ​​করা হয়।

func TestGetWeather(t *testing.T) {
	// tests struct initialized with "San Francisco" and "New York"

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// Pass nil for tool.Context since GetWeather doesn't use it
			result, err := GetWeather(nil, GetWeatherArgs{City: tt.city})
			if err != nil {
				t.Fatalf("GetWeather() error = %v", err)
			}
			if !strings.Contains(result.Weather, tt.wantCity) {
				t.Errorf("GetWeather() = %v, want city %v in response", result.Weather, tt.wantCity)
			}
		})
	}
}

এন্ড-টু-এন্ড টেস্টগুলো যাচাই করে যে এজেন্টটি সার্ভার হিসেবে চলার সময় সঠিকভাবে কাজ করছে কিনা, বিশেষ করে A2A বা এজেন্ট-টু-এজেন্ট প্রোটোকল সাপোর্ট সঠিকভাবে কাজ করছে কিনা তা পরীক্ষা করে। E2E টেস্টগুলো সার্ভারের একটি বাস্তব ইনস্ট্যান্স চালু করে, তাতে HTTP রিকোয়েস্ট পাঠায় এবং রেসপন্সগুলো পরীক্ষা করে।

এখানে e2e/integration/server_e2e_test.go থেকে একটি অংশ দেওয়া হলো:

func TestA2AMessageSend(t *testing.T) {
    if testing.Short() { t.Skip("Skipping E2E test in short mode") }

    // Start server (local variable to avoid race conditions)
    t.Log("Starting server process")
    serverProcess := startServer(t)
    defer stopServer(t, serverProcess)

    if !waitForServer(t, 90*time.Second) {
	    t.Fatal("Server failed to start")
    }
    t.Log("Server process started")
    // ...
}

আপনি মেকফাইল ব্যবহার করে স্থানীয়ভাবে সমস্ত পরীক্ষা চালাতে পারেন:

make test

৭. মোতায়েন

যখন আপনি আপনার এজেন্টটি সবার সাথে শেয়ার করতে বা প্রোডাকশন ইকোসিস্টেমের সাথে সংযুক্ত করতে প্রস্তুত হবেন, তখন অন্তর্ভুক্ত ডিপ্লয় কমান্ডটি চালান:

make deploy

এই কমান্ডটি --source . . ফ্ল্যাগের মাধ্যমে সক্রিয় হয়ে গুগল ক্লাউড বিল্ডপ্যাকস ব্যবহার করে সোর্স থেকে আপনার অ্যাপ্লিকেশনটি স্বয়ংক্রিয়ভাবে বিল্ড করে। এটি বেশ কিছু প্রোডাকশন-অপ্টিমাইজড ফ্ল্যাগ সহ এই ইমেজটি ক্লাউড রান-এ ডেপ্লয় করে: LLM অপারেশনের জন্য পর্যাপ্ত র‍্যাম সরবরাহ করতে --memory "4Gi" , এবং সিপিইউ যাতে ২৪/৭ বরাদ্দ থাকে তা নিশ্চিত করতে --no-cpu-throttling , যা কোল্ড স্টার্ট প্রতিরোধ করতে পারে এবং এজেন্ট ইন্টারঅ্যাকশনে দ্রুত প্রতিক্রিয়া নিশ্চিত করে।

আপনার এজেন্ট যাতে নিরাপদে চলে, তা নিশ্চিত করতে সিস্টেমটি একটি কঠোর কনফিগারেশন সহ স্থাপন করা হয়। এতে --no-allow-unauthenticated ব্যবহার করে ডিফল্টরূপে সমস্ত পাবলিক অ্যাক্সেস ব্লক করা হয় এবং যেকোনো অনুরোধের জন্য আইডেন্টিটি অ্যান্ড অ্যাক্সেস ম্যানেজমেন্ট (IAM) অথেনটিকেশন প্রয়োজন হয়। এছাড়াও এটি GOOGLE_GENAI_USE_VERTEXAI=True সহ বিভিন্ন এনভায়রনমেন্ট ভেরিয়েবল যুক্ত করে।

যেহেতু আপনার অ্যাপটি সুরক্ষিত, তাই ব্রাউজারের মাধ্যমে নিরাপদে এটি অ্যাক্সেস করার জন্য আপনাকে আইডেন্টিটি-অ্যাওয়ার প্রক্সি (IAP) চালু করতে হবে। ক্লাউড ডকুমেন্টেশনের 'Enable IAP for Cloud Run' অংশে ধাপে ধাপে নির্দেশাবলী দেওয়া আছে।

একবার IAP সক্রিয় হয়ে গেলে এবং আপনার ইমেল প্রিন্সিপাল হিসেবে যুক্ত হয়ে গেলে, আপনি ডেপ্লয়মেন্টের পরে প্রদত্ত সার্ভিস ইউআরএল-এ যেতে পারবেন। বেস সার্ভিস ইউআরএল দেখলে আপনি ডেপ্লয় করা এজেন্ট কার্ডটি দেখতে পাবেন। এই JSON কাঠামোটি আপনার এজেন্টের স্ট্যান্ডার্ড ইন্টারফেস হিসেবে কাজ করে, যার ফলে অন্যান্য এজেন্ট, অর্কেস্ট্রেটর বা ব্যবহারকারী UI এটিকে ডায়নামিকভাবে খুঁজে পেতে এবং ব্যবহার করতে পারে।

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

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

আপনি আপনার ক্লাউড প্রজেক্টটি ডিলিট করতে পারেন, যার ফলে এর মধ্যে ব্যবহৃত সমস্ত রিসোর্সের বিলিং বন্ধ হয়ে যাবে:

gcloud projects delete $PROJECT_ID

আপনি আপনার ক্লাউড শেল ডিস্ক থেকে কোডল্যাব প্রজেক্ট ডিরেক্টরিটিও মুছে ফেলতে পারেন:

rm -rf ~/my-first-go-agent

৯. অভিনন্দন!

🎊 মিশন সম্পন্ন! আপনি এজেন্ট ডেভেলপমেন্ট কিট ব্যবহার করে Go-তে সফলভাবে একটি AI এজেন্ট স্কাফোল্ড, টেস্ট এবং ডিপ্লয় করেছেন।

আপনি যা অর্জন করেছেন:

• এজেন্ট স্টার্টার প্যাক ব্যবহার করে একটি প্রাথমিক কাঠামোগত বেসলাইন তৈরি করা হয়েছে।
• এজেন্ট UI এবং কোড স্থানীয়ভাবে যাচাই ও পরীক্ষা করা হয়েছে।
• LLM-এর আচরণগুলোকে Go অবজেক্টে ম্যাপ করে এমন টাইপড স্কিমা ও ফাংশনগুলো গভীরভাবে খতিয়ে দেখা হয়েছে।
• ক্লাউড রানে গো সার্ভিসটি ডেপ্লয় করা হয়েছে।

এরপর কী?

• ADK ডকুমেন্টেশন : অ্যাডভান্সড প্যাটার্ন, মাল্টি-এজেন্ট অর্কেস্ট্রেশন এবং মেমরি সিস্টেমের উপর সম্পূর্ণ নির্দেশিকা
• এজেন্ট স্টার্টার প্যাক : মাল্টি-এজেন্ট সিস্টেম এবং জটিল আর্কিটেকচার সহ টেমপ্লেটগুলি অন্বেষণ করুন
• ক্লাউড রান ডকুমেন্টেশন : পারফরম্যান্স অপ্টিমাইজেশন, স্কেলিং কৌশল এবং নিরাপত্তা সংক্রান্ত সেরা অনুশীলনগুলির উপর গভীর আলোচনা
• গো কনকারেন্সি প্যাটার্নস : গোরুটিন এবং চ্যানেল বোঝা আপনাকে আরও কার্যকর এজেন্ট টুলিং তৈরি করতে সাহায্য করবে।
• ভার্টেক্স এআই এজেন্ট ইঞ্জিন : অন্তর্নির্মিত অর্কেস্ট্রেশন এবং টুলিং সহ পরিচালিত এজেন্ট পরিকাঠামোর জন্য