Go için ADK ile Temsilci Başlangıç Paketi

1. Giriş

Python, model eğitimi ve araştırmaları için popülerliğini korusa da yapay zeka aracılarını sunma ve düzenleme gereksinimleri, Go'nun güçlü yönleriyle (düşük gecikme, yüksek eşzamanlılık ve tip güvenliği) yakından ilişkilidir.

Prototip aşamasından üretim aracısına geçiş, Go'nun son derece iyi ele alabileceği mühendislik zorlukları ortaya çıkarır. Go'nun statik türü, yapılandırılmış LLM çıkışları ayrıştırılırken çalışma zamanı hatalarını ortadan kaldırır. İşletim sistemi iş parçacıkları için birkaç megabayt olan yığın belleğinin aksine, yalnızca birkaç kilobayt yığın belleğiyle başlayan hafif goroutine'leri sayesinde aracılar, ağır iş parçacığı yönetiminin ek yükü olmadan binlerce eşzamanlı araç yürütmesini işleyebilir.

Google'ın Agent Development Kit (ADK), bu mimari avantajlar ile üretken yapay zeka arasındaki boşluğu doldurur. Bu kılavuzda yeni bir proje oluşturup Google Cloud'da güvenli bir mikro hizmet olarak dağıtacaksınız.

Yapacaklarınız:

• Temsilci Başlangıç Paketi'ni kullanarak üretime hazır bir temsilci projesi oluşturma
• Aracınızda hata ayıklama ve test işlemleri yapmak için yerel Agent Development Kit web kullanıcı arayüzünü kullanın.
• Go tabanlı ADK aracı mantığını geliştirme ve anlama
• Birim ve uçtan uca (E2E) testleri çalıştırma
• Aracı Cloud Run'a güvenli bir şekilde dağıtma

Şunlara ihtiyacınız olacaktır:

• Chrome gibi bir web tarayıcısı
• Faturalandırmanın etkin olduğu bir Google Cloud projesi

2. Başlamadan önce

Google Cloud projesi oluşturma

Henüz bir hesabınız yoksa:

1. Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun.

Cloud Shell'i Başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır. Bu laboratuvarda birincil geliştirme ortamınız olarak kullanılacak.

1. Google Cloud Console'un üst kısmından Cloud Shell'i etkinleştir'i tıklayın.
2. Cloud Shell'e bağlandıktan sonra Cloud Shell'de kimlik doğrulamanızı doğrulamak için şu komutu çalıştırın:

gcloud auth list

3. Projenizin gcloud ile kullanılacak şekilde yapılandırıldığını doğrulamak için aşağıdaki komutu çalıştırın:

gcloud config get project

4. Projenin beklendiği gibi olduğunu onaylayın ve ardından proje kimliğinizi ayarlamak için aşağıdaki komutu çalıştırın:

export PROJECT_ID=$(gcloud config get project)

3. Temsilci Başlangıç Paketi'ni kullanmaya başlama

İyi haber şu ki, sıfırdan başlamanıza gerek yok. Agent Starter Pack, CI/CD ardışık düzenleri, altyapı yapılandırması ve ortak metin kodu dahil olmak üzere üretime hazır bir klasör yapısı oluşturan bir CLI aracıdır.

Başlamak için derleme oluşturma komutunu uvx ile çalıştırmanız yeterlidir:

uvx agent-starter-pack create

KSA, etkileşimli bir kurulum sürecinde size rehberlik eder. Bu proje için aşağıdaki seçenekleri belirleyin:

• Proje Adı: my-first-go-agent
• Şablon: Seçenek 6 (Go ADK, A2A ile Go aracısı)
• CI/CD: 3. seçenek (GitHub Actions)
• Bölge: us-central1

Araç, Google Cloud ile otomatik olarak kimlik doğrular, gerekli Vertex AI API'lerini etkinleştirir ve yerel ortamınızı yapılandırır.

Yeşil Başarılı! mesajını gördüğünüzde devam edebilirsiniz.

4. Aracıyı Yerel Olarak Görselleştirme

ADK'nın en kullanışlı özelliklerinden biri, temsilcinizi dağıtmadan önce görsel olarak hata ayıklama yapabilme imkanıdır. Aşağıdaki komutları çalıştırarak yerleşik kullanıcı arayüzüne sahip yerel bir geliştirme sunucusu başlatırsınız. Evet, bir sohbet penceresi var ancak etkinlikleri, araç çağrılarını ve daha fazlasını izleyerek bunun çok ötesine geçiyor.

Proje dizininize geçin ve deneme alanını başlatın:

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

Playground çalıştıktan sonra, yeni oluşturduğunuz temsilciyle etkileşim kurmak için Cloud Shell'de web önizlemesini açın.

Temsilci, ReAct (Reasoning and Acting) modeliyle yapılandırılır. Bu model, ajan tabanlı yapay zekada temel bir çerçeve haline gelmiştir. ReAct kalıbının sürekli "Düşünme", "Eylem" ve "Gözlem" döngüsü, sorun çözme ve yorumlanabilirliği artırarak aracının karar verme sürecini şeffaf hale getirir.

Örneğin, hava durumunu sorduğunuzda aracı, amacı tanır, get_weather aracını çağırır ve yapılandırılmış verileri döndürür.

5. Kodu anlama

Ajanın nasıl çalıştığını gördüğümüze göre, bu işlevi sağlayan Go koduna göz atalım. Mantık agent/agent.go içinde yer alır. Bu dosya, araç tanımlarını, model yapılandırmasını ve başlatmayı yönetir.

ADK, Büyük Dil Modeli'nin (LLM) kodunuzla nasıl etkileşim kuracağını tanımlamak için standart Go yapılarını kullanır. Hava durumu aracımızın giriş parametrelerini tanımlamak için json ve jsonschema etiketleriyle bir yapı tanımlıyoruz:

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

GetWeatherResult, araç yürütüldükten sonra aracıya döndürülen verilerin yapısını tanımlar:

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

GetWeather, tool.Context ve bağımsız değişkenler yapısını kabul eden, iş mantığını yürüten ve sonuç yapısını döndüren standart bir Go işlevidir:

// 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 işlevi, uygulama başlatıcının gerektirdiği agent.Agent örneğini oluşturup döndürmekten sorumludur. Model yapılandırmasını başlatarak ve gemini-2.5-flash tarafından desteklenen bir genai.BackendVertexAI model örneği oluşturarak başlar.

Ardından, yerel GetWeather işlevini functiontool içine sarmalayarak Go kodu ile LLM arasındaki boşluğu doldurur. Bu adımda araç, get_weather adıyla kaydedilir ve modelin bağlamı için gerekli açıklama sağlanır. Son olarak, başlatılan Gemini modelini, aracının davranışını tanımlayan sistem talimatlarını ve mevcut araçların dilimini tek bir birimde birleştiren llmagent.New kullanarak aracı oluşturur.

// 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. Test

Proje, hem dahili mantık için birim testleri hem de sunucu entegrasyonu için uçtan uca testler içerir.

agent/agent_test.go içinde, çıkış dizesinin beklentilerle eşleştiğini doğrulamak için GetWeather işlevi bir dizi test senaryosuyla çağrılır.

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)
			}
		})
	}
}

Uçtan uca testler, aracının sunucu olarak çalışırken doğru şekilde çalıştığını doğrular. Özellikle A2A veya Agent-to-Agent protokol desteğinin doğru şekilde çalıştığı kontrol edilir. Uçtan uca testler, sunucunun gerçek bir örneğini başlatır, sunucuya HTTP istekleri gönderir ve yanıtları kontrol eder.

e2e/integration/server_e2e_test.go kaynağından bir snippet:

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")
    // ...
}

Makefile'ı kullanarak tüm testleri yerel olarak çalıştırabilirsiniz:

make test

7. Dağıtım

Aracınızı dünyayla paylaşmaya veya üretim ekosistemlerine bağlamaya hazır olduğunuzda, dahil edilen dağıtma komutunu çalıştırın:

make deploy

Bu komut, --source . işaretiyle tetiklenen Google Cloud Buildpacks'i kullanarak uygulamanızı otomatik olarak kaynaktan oluşturur. Bu görüntüyü, Cloud Run'a üretim için optimize edilmiş çeşitli işaretlerle dağıtır: --memory "4Gi" LLM işlemleri için yeterli RAM sağlamak ve --no-cpu-throttling CPU'nun 7/24 ayrılmasını sağlamak. Bu sayede soğuk başlatmalar önlenebilir ve aracı etkileşimlerinde hızlı yanıtlar verilebilir.

Aracınızın güvenli bir şekilde çalışmasını sağlamak için sistem, varsayılan olarak tüm herkese açık erişimi engellemek üzere --no-allow-unauthenticated kullanılarak katı bir yapılandırmayla dağıtılır ve tüm istekler için Identity and Access Management (IAM) kimlik doğrulaması gerekir. Ayrıca GOOGLE_GENAI_USE_VERTEXAI=True dahil olmak üzere ortam değişkenlerini de ekler.

Uygulamanız güvenli olduğundan, tarayıcı üzerinden güvenli bir şekilde erişmek için Identity-Aware Proxy'yi (IAP) etkinleştirmeniz gerekir. Cloud belgelerinde Cloud Run için IAP'yi etkinleştirme başlıklı adım adım talimatlar yer almaktadır.

IAP etkinleştirildikten ve e-postanız asıl kullanıcı olarak eklendikten sonra, dağıtımdan sonra sağlanan hizmet URL'sine gidebilirsiniz. Temel hizmet URL'sini görüntüleyerek dağıtılan Agent Card'ı görebilirsiniz. Bu JSON yapısı, aracınızın standart arayüzü olarak işlev görür. Bu sayede, diğer aracılar, düzenleyiciler veya kullanıcıya yönelik kullanıcı arayüzleri tarafından dinamik olarak keşfedilip kullanılabilir.

8. Temizleme

Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu Codelab sırasında oluşturulan kaynakları silin.

Cloud projenizi silebilirsiniz. Bu durumda, proje içinde kullanılan tüm kaynaklar için faturalandırma durdurulur:

gcloud projects delete $PROJECT_ID

Ayrıca, Cloud Shell diskinizden codelab proje dizinini de silebilirsiniz:

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

9. Tebrikler!

🎊 Görev Tamamlandı! Agent Development Kit'i kullanarak Go'da bir yapay zeka aracını başarıyla oluşturup test ettiniz ve dağıttınız.

Başarılarınız:

• Temsilci Başlangıç Paketi'ni kullanarak ilk yapılandırılmış temel çizgiyi oluşturma
• Temsilci kullanıcı arayüzünü ve kodunu yerel olarak doğrulayıp test etme
• Yazılan şemaları ve LLM davranışlarını Go nesneleriyle eşleyen işlevleri inceledi.
• Go hizmetini Cloud Run'a dağıtma

Sırada ne var?

• ADK Dokümanları: Gelişmiş kalıplar, çoklu aracı düzenleme ve bellek sistemleri hakkında eksiksiz kılavuzlar
• Temsilci Başlangıç Paketi: Çoklu temsilci sistemleri ve karmaşık mimariler de dahil olmak üzere şablonları keşfedin.
• Cloud Run Belgeleri: Performans optimizasyonu, ölçeklendirme stratejileri ve güvenlik ile ilgili en iyi uygulamalar hakkında ayrıntılı bilgiler
• Go Eşzamanlılık Kalıpları: Goroutine'leri ve kanalları anlamak, daha verimli aracı araçları oluşturmanıza yardımcı olur.
• Vertex AI Agent Engine: Yerleşik düzenleme ve araçlarla yönetilen aracı altyapısı için