Agent Starter Pack dengan ADK untuk Go

1. Pengantar

Meskipun Python tetap populer untuk pelatihan dan riset model, persyaratan untuk penyajian dan pengoordinasian agen AI sangat sesuai dengan keunggulan Go: latensi rendah, konkurensi tinggi, dan keamanan jenis.

Beralih dari prototipe ke agen produksi menimbulkan tantangan teknik yang dapat ditangani Go dengan sangat baik. Pengetikan statis Go menghilangkan error runtime saat mengurai output LLM terstruktur. Goroutine-nya yang ringan, yang dimulai dengan hanya beberapa kilobyte memori stack dibandingkan dengan beberapa megabyte untuk thread OS, memungkinkan agen menangani ribuan eksekusi alat serentak tanpa overhead pengelolaan thread yang berat.

Agent Development Kit (ADK) Google menjembatani kesenjangan antara keunggulan arsitektur ini dan AI generatif. Dalam panduan ini, Anda akan membuat project baru dan men-deploy-nya sebagai mikroservice yang aman di Google Cloud.

Yang akan Anda lakukan:

• Buat project agen yang siap produksi menggunakan Agent Starter Pack
• Gunakan UI web Agent Development Kit lokal untuk men-debug dan menguji agen Anda
• Mengembangkan dan memahami logika agen ADK berbasis Go
• Menjalankan pengujian unit dan end-to-end (E2E)
• Men-deploy agen secara aman ke Cloud Run

Hal-hal yang Anda butuhkan:

• Browser web seperti Chrome
• Project Google Cloud yang mengaktifkan penagihan

2. Sebelum memulai

Buat Project Google Cloud

Jika Anda belum memilikinya:

1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
2. Pastikan penagihan diaktifkan untuk project Cloud Anda.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan. Instance ini akan berfungsi sebagai lingkungan pengembangan utama Anda untuk lab ini.

1. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
2. Setelah terhubung ke Cloud Shell, jalankan perintah ini untuk memverifikasi autentikasi Anda di Cloud Shell:

gcloud auth list

3. Jalankan perintah berikut untuk mengonfirmasi bahwa project Anda dikonfigurasi untuk digunakan dengan gcloud:

gcloud config get project

4. Konfirmasi bahwa project sudah sesuai dengan yang diharapkan, lalu jalankan perintah di bawah untuk menetapkan project ID Anda:

export PROJECT_ID=$(gcloud config get project)

3. Mulai Menggunakan Paket Starter Agen

Kabar baiknya, Anda tidak perlu memulai dari awal. Agent Starter Pack adalah alat CLI yang membuat struktur folder siap produksi, termasuk pipeline CI/CD, konfigurasi infrastruktur, dan kode boilerplate.

Untuk memulai, cukup jalankan perintah pembuatan build dengan uvx:

uvx agent-starter-pack create

CLI akan memandu Anda melalui penyiapan interaktif. Untuk project ini, pilih opsi berikut:

• Nama Proyek: my-first-go-agent
• Template: Opsi 6 (Go ADK, Go agent with A2A)
• CI/CD: Opsi 3 (GitHub Actions)
• Region: us-central1

Alat ini otomatis melakukan autentikasi dengan Google Cloud, mengaktifkan Vertex AI API yang diperlukan, dan mengonfigurasi lingkungan lokal Anda.

Setelah Anda melihat pesan Success! berwarna hijau, Anda siap untuk melanjutkan.

4. Memvisualisasikan Agen Secara Lokal

Salah satu fitur ADK yang paling praktis adalah kemampuan untuk men-debug agen Anda secara visual sebelum men-deploy-nya. Dengan menjalankan perintah di bawah, Anda meluncurkan server pengembangan lokal dengan UI bawaan. Ya, ada jendela chat, tetapi kemampuannya jauh melampaui itu dengan melacak peristiwa, panggilan alat, dan banyak lagi.

Ubah ke direktori project Anda dan mulai playground:

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

Setelah playground berjalan, buka pratinjau web di Cloud Shell untuk berinteraksi dengan agen yang baru dibuat.

Agen dikonfigurasi dengan pola ReAct (Reasoning and Acting)—framework yang telah menjadi dasar dalam AI agentik. Loop berkelanjutan pola ReAct yang terdiri dari "Pemikiran", "Tindakan", dan "Pengamatan" meningkatkan pemecahan masalah dan kemampuan interpretasi, sehingga membuat proses pengambilan keputusan agen menjadi transparan.

Misalnya, jika Anda menanyakan cuaca, agen akan mengenali maksudnya, memanggil alat get_weather, dan menampilkan data terstruktur.

5. Memahami Kode

Setelah melihat cara kerja agen, mari kita lihat kode Go yang membuatnya berfungsi. Logika berada di agent/agent.go. File ini menangani definisi alat, konfigurasi model, dan inisialisasi.

ADK menggunakan struct Go standar untuk menentukan cara Model Bahasa Besar (LLM) berinteraksi dengan kode Anda. Untuk menentukan parameter input alat cuaca, kita menentukan struct dengan tag json dan jsonschema:

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

GetWeatherResult menentukan struktur data yang ditampilkan ke agen setelah alat dijalankan:

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

GetWeather adalah fungsi Go standar yang menerima tool.Context dan struct argumen, menjalankan logika bisnis, dan menampilkan struct hasil:

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

Fungsi NewRootAgent bertanggung jawab untuk merakit dan menampilkan instance agent.Agent yang diperlukan peluncur aplikasi. Proses ini dimulai dengan menginisialisasi konfigurasi model, membuat instance model gemini-2.5-flash yang didukung oleh genai.BackendVertexAI.

Selanjutnya, kode ini menjembatani kesenjangan antara kode Go dan LLM dengan membungkus fungsi GetWeather lokal ke dalam functiontool. Langkah ini mendaftarkan alat dengan nama get_weather dan memberikan deskripsi yang diperlukan untuk konteks model. Terakhir, kode ini membuat agen menggunakan llmagent.New, yang menggabungkan model Gemini yang diinisialisasi, petunjuk sistem yang menentukan perilaku agen, dan slice alat yang tersedia menjadi satu unit.

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

Project ini berisi pengujian unit untuk logika internal, dan pengujian menyeluruh untuk integrasi server.

Di agent/agent_test.go, fungsi GetWeather dipanggil dengan serangkaian kasus pengujian untuk memverifikasi bahwa string output cocok dengan yang diharapkan.

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

Pengujian end-to-end memverifikasi bahwa agen berfungsi dengan benar saat berjalan sebagai server, khususnya memeriksa apakah dukungan protokol A2A atau Agent-to-Agent berfungsi dengan benar. Pengujian E2E memulai instance server yang sebenarnya, mengirim permintaan HTTP ke server tersebut, dan memeriksa responsnya.

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

Anda dapat menjalankan semua pengujian secara lokal menggunakan makefile:

make test

7. Deployment

Setelah Anda siap membagikan agen Anda kepada dunia atau menghubungkannya ke ekosistem produksi, jalankan perintah deployment yang disertakan:

make deploy

Perintah ini otomatis membangun aplikasi Anda dari sumber menggunakan Buildpack Google Cloud, yang dipicu oleh flag --source .. Image ini di-deploy ke Cloud Run dengan beberapa tanda yang dioptimalkan untuk produksi: --memory "4Gi" untuk menyediakan RAM yang cukup untuk operasi LLM, dan --no-cpu-throttling untuk memastikan CPU tetap dialokasikan 24/7, yang dapat mencegah cold start dan memastikan respons cepat dalam interaksi agen.

Untuk memastikan agen Anda berjalan dengan aman, sistem di-deploy dengan konfigurasi ketat menggunakan --no-allow-unauthenticated untuk memblokir semua akses publik secara default, sehingga memerlukan autentikasi Identity and Access Management (IAM) untuk setiap permintaan. Hal ini juga memasukkan variabel lingkungan termasuk GOOGLE_GENAI_USE_VERTEXAI=True.

Karena aplikasi Anda diamankan, Anda harus mengaktifkan Identity-Aware Proxy (IAP) untuk mengaksesnya dengan aman melalui browser. Dokumentasi Cloud memberikan petunjuk langkah demi langkah di Mengaktifkan IAP untuk Cloud Run.

Setelah IAP diaktifkan dan email Anda ditambahkan sebagai prinsipal, Anda dapat membuka URL Layanan yang diberikan setelah deployment. Dengan melihat URL Layanan dasar, Anda dapat melihat Kartu Agen yang di-deploy. Struktur JSON ini berfungsi sebagai antarmuka standar agen Anda, sehingga dapat ditemukan dan digunakan secara dinamis oleh agen, pengelola, atau UI yang berinteraksi dengan pengguna.

8. Pembersihan

Untuk menghindari biaya berkelanjutan pada akun Google Cloud Anda, hapus resource yang dibuat selama Codelab ini.

Anda dapat menghapus project Cloud, yang akan menghentikan penagihan untuk semua resource yang digunakan di dalamnya:

gcloud projects delete $PROJECT_ID

Anda juga dapat menghapus direktori project codelab dari disk Cloud Shell:

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

9. Selamat!

🎊 Misi Selesai! Anda telah berhasil membuat struktur, menguji, dan men-deploy Agen AI di Go menggunakan Agent Development Kit.

Yang telah Anda capai:

• Membuat struktur dasar terstruktur awal menggunakan Agent Starter Pack
• Memverifikasi dan menguji UI dan kode agen secara lokal
• Mempelajari skema dan fungsi yang diketik yang memetakan perilaku LLM ke objek Go
• Men-deploy layanan Go ke Cloud Run

Apa langkah selanjutnya?

• Dokumentasi ADK: Panduan lengkap tentang pola lanjutan, orkestrasi multiagen, dan sistem memori
• Agent Starter Pack: Jelajahi template, termasuk sistem multi-agen dan arsitektur kompleks
• Dokumentasi Cloud Run: Pembahasan mendalam tentang pengoptimalan performa, strategi penskalaan, dan praktik terbaik keamanan
• Pola Concurrency Go: Memahami goroutine dan channel akan membantu Anda membangun alat agen yang lebih efisien
• Vertex AI Agent Engine: Untuk infrastruktur agen terkelola dengan orkestrasi dan alat bawaan