Go के लिए ADK के साथ एजेंट स्टार्टर पैक

1. परिचय

Go के साथ ADK

मॉडल ट्रेनिंग और रिसर्च के लिए, Python अब भी एक लोकप्रिय भाषा है. हालांकि, एआई एजेंट को सर्व करने और ऑर्केस्ट्रेट करने की ज़रूरतें, Go की खूबियों से काफ़ी मिलती-जुलती हैं. जैसे, कम समय में काम पूरा करना, एक साथ कई काम करना, और टाइप की सुरक्षा.

प्रोटोटाइप से प्रोडक्शन एजेंट पर स्विच करने से, इंजीनियरिंग से जुड़ी समस्याएं आती हैं. Go इन समस्याओं को बहुत अच्छी तरह से हल कर सकता है. Go में स्टैटिक टाइपिंग की सुविधा होती है. इससे, एलएलएम के स्ट्रक्चर्ड आउटपुट को पार्स करते समय रनटाइम की गड़बड़ियां नहीं होती हैं. इसमें हल्की गोरूटीन होती हैं. ये ओएस थ्रेड के लिए कई मेगाबाइट की तुलना में, सिर्फ़ कुछ किलोबाइट की स्टैक मेमोरी से शुरू होती हैं. इससे एजेंट, थ्रेड मैनेजमेंट के ओवरहेड के बिना, एक साथ कई टूल को एक्ज़ीक्यूट कर सकते हैं.

Google का एजेंट डेवलपमेंट किट (एडीके), आर्किटेक्चर से जुड़े इन फ़ायदों और जनरेटिव एआई के बीच के अंतर को कम करता है. इस गाइड में, आपको एक नया प्रोजेक्ट बनाने और उसे Google Cloud पर सुरक्षित माइक्रोसेवा के तौर पर डिप्लॉय करने का तरीका बताया जाएगा.

आपको क्या करना होगा:

Agent Starter Pack का इस्तेमाल करके, प्रोडक्शन के लिए तैयार एजेंट प्रोजेक्ट को स्कैफ़ोल्ड करना
अपने एजेंट को डीबग और टेस्ट करने के लिए, लोकल एजेंट डेवलपमेंट किट के वेब यूज़र इंटरफ़ेस का इस्तेमाल करना
Go पर आधारित ADK एजेंट लॉजिक को डेवलप करना और समझना
यूनिट और एंड-टू-एंड (E2E) टेस्ट चलाना
एजेंट को Cloud Run पर सुरक्षित तरीके से डिप्लॉय करना

आपको किन चीज़ों की ज़रूरत होगी:

कोई वेब ब्राउज़र, जैसे कि Chrome
बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट

2. शुरू करने से पहले

Google Cloud प्रोजेक्ट बनाना

अगर आपके पास पहले से कोई खाता नहीं है, तो:

Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो.

Cloud Shell शुरू करना

Cloud Shell, Google Cloud में चलने वाला एक कमांड-लाइन एनवायरमेंट है. इसमें ज़रूरी टूल पहले से लोड होते हैं. यह इस लैब के लिए, आपके मुख्य डेवलपमेंट एनवायरमेंट के तौर पर काम करेगा.

Google Cloud कंसोल में सबसे ऊपर मौजूद, Cloud Shell चालू करें पर क्लिक करें.
Cloud Shell से कनेक्ट होने के बाद, Cloud Shell में अपनी पुष्टि करने के लिए, यह कमांड चलाएं:

gcloud auth list

यह पुष्टि करने के लिए कि आपका प्रोजेक्ट gcloud के साथ इस्तेमाल करने के लिए कॉन्फ़िगर किया गया है, यह निर्देश चलाएं:

gcloud config get project

पुष्टि करें कि प्रोजेक्ट आपकी उम्मीद के मुताबिक है. इसके बाद, अपना प्रोजेक्ट आईडी सेट करने के लिए, यहां दिया गया निर्देश चलाएं:

export PROJECT_ID=$(gcloud config get project)

3. एजेंट स्टार्टर पैक का इस्तेमाल शुरू करना

अच्छी बात यह है कि आपको शुरुआत से कुछ भी करने की ज़रूरत नहीं है. Agent Starter Pack एक सीएलआई टूल है. यह प्रोडक्शन के लिए तैयार फ़ोल्डर स्ट्रक्चर बनाता है. इसमें सीआई/सीडी पाइपलाइन, इंफ़्रास्ट्रक्चर कॉन्फ़िगरेशन, और बॉयलरप्लेट कोड शामिल होता है.

शुरू करने के लिए, uvx के साथ बिल्ड बनाने का निर्देश चलाएं:

uvx agent-starter-pack create

सीएलआई, इंटरैक्टिव सेटअप के बारे में आपकी मदद करेगा. इस प्रोजेक्ट के लिए, ये विकल्प चुनें:

प्रोजेक्ट का नाम: my-first-go-agent
टेंप्लेट: विकल्प 6 (Go ADK, Go agent with A2A)
CI/CD: विकल्प 3 (GitHub Actions)
देश/इलाका: us-central1

एजेंट के लिए गाइड का सेटअप

जब आपको हरे रंग का हो गया! मैसेज दिखे, तब आगे बढ़ें.

सफलता का मैसेज

4. एजेंट को स्थानीय तौर पर विज़ुअलाइज़ करना

ADK की सबसे काम की सुविधाओं में से एक यह है कि एजेंट को डिप्लॉय करने से पहले, उसे विज़ुअली डीबग किया जा सकता है. नीचे दिए गए कमांड चलाने पर, आपको बिल्ट-इन यूज़र इंटरफ़ेस (यूआई) वाला लोकल डेवलपमेंट सर्वर लॉन्च करने का विकल्प मिलता है. हाँ, इसमें चैट विंडो है. हालाँकि, यह इवेंट, टूल कॉल वगैरह को ट्रैक करने के साथ-साथ और भी बहुत कुछ करता है.

अपनी प्रोजेक्ट डायरेक्ट्री पर जाएं और प्लेग्राउंड शुरू करें:

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

प्लेग्राउंड चालू होने के बाद, Cloud Shell में वेब प्रीव्यू खोलें, ताकि बनाए गए नए एजेंट के साथ इंटरैक्ट किया जा सके.

एजेंट को ReAct (Reasoning and Acting) पैटर्न के साथ कॉन्फ़िगर किया गया है. यह एक ऐसा फ़्रेमवर्क है जो एजेंटिक एआई में बुनियादी तौर पर इस्तेमाल किया जाता है. ReAct पैटर्न में "सोचना", "कार्रवाई करना", और "निरीक्षण करना" का लगातार लूप होता है. इससे समस्या हल करने और व्याख्या करने की क्षमता बढ़ती है. साथ ही, एजेंट के फ़ैसले लेने की प्रोसेस पारदर्शी हो जाती है.

उदाहरण के लिए, अगर आपने मौसम के बारे में पूछा, तो एजेंट आपके सवाल को समझता है. इसके बाद, वह get_weather टूल को चालू करता है और स्ट्रक्चर्ड डेटा दिखाता है.

Playground का यूज़र इंटरफ़ेस (यूआई)

5. कोड को समझना

अब जब हमने एजेंट को काम करते हुए देख लिया है, तो आइए उस Go कोड को देखें जिसकी वजह से यह काम करता है. लॉजिक agent/agent.go में मौजूद होता है. यह फ़ाइल, टूल डेफ़िनिशन, मॉडल कॉन्फ़िगरेशन, और शुरुआत को मैनेज करती है.

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 कोड और एलएलएम के बीच के अंतर को कम करता है. इस चरण में, टूल को 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
}

6. टेस्ट करना

प्रोजेक्ट में, इंटरनल लॉजिक के लिए यूनिट टेस्ट और सर्वर इंटिग्रेशन के लिए एंड-टू-एंड टेस्ट, दोनों शामिल हैं.

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 टेस्ट, सर्वर का एक असली इंस्टेंस शुरू करते हैं. साथ ही, इस पर एचटीटीपी अनुरोध भेजते हैं और जवाबों की जांच करते हैं.

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

7. डिप्लॉयमेंट

जब आपको अपने एजेंट को दुनिया के साथ शेयर करना हो या उसे प्रोडक्शन इकोसिस्टम से कनेक्ट करना हो, तो शामिल की गई डिप्लॉय कमांड चलाएं:

make deploy

यह कमांड, --source . फ़्लैग से ट्रिगर होकर, Google Cloud Buildpacks का इस्तेमाल करके, सोर्स से आपके ऐप्लिकेशन को अपने-आप बनाती है. यह इमेज, Cloud Run पर कई प्रोडक्शन-ऑप्टिमाइज़ किए गए फ़्लैग के साथ डिप्लॉय की जाती है: --memory "4Gi" का इस्तेमाल, एलएलएम ऑपरेशंस के लिए ज़्यादा रैम उपलब्ध कराने के लिए किया जाता है. वहीं, --no-cpu-throttling का इस्तेमाल यह पक्का करने के लिए किया जाता है कि सीपीयू को हर समय ऐलोकेट किया जाए. इससे कोल्ड स्टार्ट को रोका जा सकता है और एजेंट इंटरैक्शन में तुरंत जवाब मिल सकते हैं.

यह पक्का करने के लिए कि आपका एजेंट सुरक्षित तरीके से काम करे, सिस्टम को --no-allow-unauthenticated का इस्तेमाल करके सख्त कॉन्फ़िगरेशन के साथ डिप्लॉय किया जाता है. इससे डिफ़ॉल्ट रूप से सभी सार्वजनिक ऐक्सेस ब्लॉक हो जाते हैं. साथ ही, किसी भी अनुरोध के लिए पहचान और ऐक्सेस मैनेजमेंट (IAM) की पुष्टि करना ज़रूरी हो जाता है. यह GOOGLE_GENAI_USE_VERTEXAI=True जैसे एनवायरमेंट वैरिएबल भी इंजेक्ट करता है.

डिप्लॉयमेंट सेवा का यूआरएल

IAP की सुविधा चालू करना

IAP चालू होने और आपके ईमेल को मुख्य ईमेल पते के तौर पर जोड़ने के बाद, डिप्लॉयमेंट के बाद दिए गए सेवा के यूआरएल पर जाएं. बेस सर्विस यूआरएल देखने से, आपको डिप्लॉय किया गया एजेंट कार्ड दिखता है. यह JSON स्ट्रक्चर, आपके एजेंट के स्टैंडर्ड इंटरफ़ेस के तौर पर काम करता है. इससे, अन्य एजेंट, ऑर्केस्ट्रेटर या लोगों के लिए उपलब्ध यूज़र इंटरफ़ेस (यूआई) को डाइनैमिक तरीके से एजेंट का पता लगाने और उसका इस्तेमाल करने की अनुमति मिलती है.

Agent Card

8. क्लीन अप करें

अपने Google Cloud खाते पर लगने वाले मौजूदा शुल्क से बचने के लिए, इस Codelab के दौरान बनाए गए संसाधनों को मिटाएं.

आपके पास अपना Cloud प्रोजेक्ट मिटाने का विकल्प होता है. ऐसा करने पर, उसमें इस्तेमाल किए गए सभी संसाधनों के लिए बिलिंग बंद हो जाती है:

gcloud projects delete $PROJECT_ID

Cloud Shell डिस्क से, codelab प्रोजेक्ट डायरेक्ट्री को भी मिटाया जा सकता है:

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

9. बधाई हो!

🎊 मिशन पूरा हुआ! आपने Agent Development Kit का इस्तेमाल करके, Go में एआई एजेंट को सफलतापूर्वक तैयार किया है, उसकी जांच की है, और उसे डिप्लॉय किया है.

आपको क्या मिला:

एजेंट स्टार्टर पैक का इस्तेमाल करके, शुरुआती स्ट्रक्चर्ड बेसलाइन तैयार की गई
एजेंट के यूज़र इंटरफ़ेस (यूआई) और कोड की पुष्टि की गई और स्थानीय तौर पर उसकी जांच की गई
टाइप किए गए स्कीमा और फ़ंक्शन मैपिंग एलएलएम के व्यवहारों को Go ऑब्जेक्ट में बदला
Go सेवा को Cloud Run पर डिप्लॉय किया गया हो

आगे क्या करना है?

ADK के दस्तावेज़: ऐडवांस पैटर्न, एक से ज़्यादा एजेंट को मैनेज करने की सुविधा, और मेमोरी सिस्टम के बारे में पूरी गाइड
एजेंट के लिए गाइड: मल्टी-एजेंट सिस्टम और जटिल आर्किटेक्चर के साथ-साथ, टेंप्लेट एक्सप्लोर करें
Cloud Run का दस्तावेज़: परफ़ॉर्मेंस ऑप्टिमाइज़ेशन, स्केलिंग की रणनीतियों, और सुरक्षा से जुड़े सबसे सही तरीकों के बारे में ज़्यादा जानकारी
Go Concurrency Patterns: Goroutines और चैनलों को समझने से, आपको एजेंट टूलिंग को ज़्यादा असरदार बनाने में मदद मिलेगी
Vertex AI Agent Engine: मैनेज किए गए एजेंट इन्फ़्रास्ट्रक्चर के लिए, जिसमें ऑर्केस्ट्रेशन और टूलिंग पहले से मौजूद होती है